Recuperação e reconciliação

O cliente não repete operações automaticamente. Timeout, cancelamento, falha de comunicação ou perda de resposta podem exigir reconciliação antes de decidir qualquer nova tentativa. O comportamento abaixo foi revalidado para a alpha publicada 0.1.0a5, commit dc0f2bba9927, sem homologação fiscal remota. As assinaturas e os limites das operações permanecem iguais aos do snapshot anterior.

Reconheça as duas formas de incerteza

Uma chamada pode retornar normalmente ResultadoFiscal(sucesso=False, estado="INDETERMINADO") ou "PENDENTE"; pode também lançar AcbrError com resultado_desconhecido=True. Trate ambas as superfícies. Após criar o processo de transmitir, cancelar ou inutilizar, falhas de transporte marcam incerteza mesmo sem marcador de envio observado.

resultado.envio_iniciado e o callback ao_iniciar_envio registram um marcador observado do worker. Não asseguram idempotência, aceitação remota, gravação anterior ao envio ou segurança de repetição quando o marcador não chegou. O callback também pode falhar ou ficar bloqueado.

Protocolo da aplicação para uma resposta perdida

1. Suspenda repetição automática. Marque a tentativa como pendente de reconciliação. Registre ambiente, horário, operação e identificador interno, sem XML, senha ou PFX em logs.
2. Preserve os materiais originais. Guarde XML assinado, chave e recibos/protocolos existentes em armazenamento protegido. Não regenere documento com nova numeração para contornar uma resposta ausente.
3. Confira o diagnóstico técnico. Preserve código, etapa, status_envio, resultado_desconhecido e limpeza_confirmada. Se a limpeza não foi confirmada, não reutilize a instância.
4. Reconcilie com o histórico completo. consultar(Consulta(...), allow_network=True) é uma API implementada, mas sua integração de rede neste snapshot só foi testada com protocolo simulado. Qualquer uso fiscal real precisa de validação controlada e autorização própria. Use o procedimento homologado da organização para decidir como conferir a situação.
5. Associe a evidência à tentativa original. Só conclua o estado da aplicação após conferir documento, ambiente, identidade e retorno correspondente. O cliente não oferece uma receita automática de reenvio.

Uma consulta com cStat=217 é classificada pelo snapshot como CONSULTADO, sucesso=True e status_envio="nao_autorizado". Isso não prova que uma tentativa anterior nunca chegou nem libera repetição automática. Considere incerteza anterior e histórico preservado.

AcbrError.xml_original pode conter o XML assinado original em uma falha incerta de transmissão. Em um resultado normal INDETERMINADO de transmissão, resultado.xml também é o XML original, não um XML autorizado. Esses acessos são sensíveis e não substituem a cópia protegida que a aplicação deve guardar antes da operação.

Consulta por chave e recibo

Consulta(chave, recibo=None) exige chave de 44 dígitos em todos os casos; recibo de 15 dígitos é opcional. Não há consulta somente por recibo no worker fixado. Os identificadores são strings e a verificação é estrutural. Uma consulta autorizada (100 ou 150) pode retornar sem XML. Não prometa que consultar sempre reconstruirá o documento processado.

Recuperação de XML experimental

recuperar_xml consulta a situação do XML assinado para reconstruir o XML processado. Ela não retransmite e não é distribuição DF-e ou download genérico por chave. Seus testes usam worker simulado e materiais sintéticos; não houve recuperação real na SEFAZ, A1 de contribuinte ou homologação fiscal nesta entrega.

# Assinatura de referência; este trecho não executa uma chamada.
# recuperar_xml(xml_assinado: str, *, allow_network: bool = False,
#               cancel: threading.Event | None = None) -> ResultadoFiscal

A chamada exige XML assinado original, UTF-8 não vazio até 4 MiB; CertificadoA1 na configuração; runtime íntegro com capacidade recuperarXml; e allow_network=True literal por chamada. O padrão bloqueia a operação com REDE_NAO_AUTORIZADA antes de iniciar o worker. HOMOLOGAÇÃO também usa rede real.

O exemplo recuperacao_bloqueada.py prova o bloqueio com identificação e XML sintéticos. O exemplo operacoes_simuladas.py mostra o formato das oito chamadas usando transporte simulado; nenhum deles consulta um serviço fiscal.

Sucesso de recuperação só é aceito com XML_RECUPERADO, cStat=100, chave de 44 dígitos, protocolo de 15 dígitos e XML. O diagnóstico passa a status_envio="autorizado". cStat=150 não é aceito como sucesso de recuperação neste commit, embora seja aceito como autorização em consulta/transmissão.

Uma consulta de recuperação sem sucesso pode retornar CONSULTADO; confira sucesso, c_stat, codigo, estado e diagnóstico. Não use a recuperação experimental como reconciliação universal para todos os efeitos fiscais.

Limites de responsabilidade do cliente

O SDK não fornece banco de dados, fila, numeração persistente, deduplicação, cofre de certificados ou um processo automático de reconciliação. As verificações de entrada são estruturais; assinatura local e teste simulado não comprovam aceitação fiscal remota. As oito operações estão implementadas, mas os métodos remotos continuam sem evidência de exercício fiscal nesta entrega.

Leia API pública, tratamento de falhas, configuração A1 e fontes.