Erros, timeout e TLS

Trate separadamente um resultado de operação com sucesso=False e uma exceção AcbrError. Uma rejeição de schema pode ser um resultado válido do protocolo; uma resposta truncada ou incompatível pode impedir a construção de qualquer resultado.

from acbr import AcbrError

def executar_geracao(emissor, documento):
    try:
        resultado = emissor.gerar_xml(documento)
    except AcbrError as erro:
        resumo = erro.diagnostico.to_dict()
        # Entregue somente esse resumo ao logger da aplicação.
        # Se houver incerteza, reconcilie antes de qualquer repetição.
        return {"concluido": False, "diagnostico": resumo}
    if not resultado.sucesso:
        return {"concluido": False, "diagnostico": resultado.diagnostico.to_dict()}
    return {"concluido": True, "estado": resultado.estado}

Diagnóstico por etapa

Código / família	Causa provável e ação
CONFIGURACAO_INVALIDA, CERTIFICADO_INVALIDO, CSC_INVALIDO	Confira tipo e limites dos parâmetros; os construtores não autenticam certificados/cadastros
CAMPO_DESCONHECIDO, CAMPO_SOMENTE_LEITURA, DECIMAL_INVALIDO, ENUM_INVALIDO	Consulte o campo com describe_field; corrija o documento sem inventar nomes ou defaults
CAMPO_AMBIGUO, COLECAO_REQUER_INDICE, CAMINHO_INVALIDO	Use caminho completo e [] nas coleções
XML_INVALIDO	XML ausente, UTF-8 inválido ou maior que 4 MiB
CONTRATO_INVALIDO, CONTRATO_DIVERGENTE	Cliente/contrato/runtime incompatível ou alterado; reinstale o snapshot íntegro
PLATAFORMA_NAO_SUPORTADA	Verifique sistema, arquitetura, Python x64 e glibc
RUNTIME_INCOMPLETO, RUNTIME_ALTERADO, RUNTIME_INVALIDO	Execute doctor; mantenha instalação e manifesto originais; reinstale em destino novo
RUNTIME_DOWNLOAD_FALHOU	Verifique acesso HTTPS e confiança TLS do download; arquivo previamente obtido pode ser usado com --archive
FALHA_INICIAR_MOTOR	Confira integridade, permissões de execução e compatibilidade das bibliotecas nativas
EMISSOR_OCUPADO	Há outra chamada nesta instância; coordene o trabalho na aplicação
EMISSOR_FECHADO	A instância foi encerrada; crie outra somente após tratar a operação anterior
TIMEOUT_MOTOR, OPERACAO_CANCELADA	Prazo/cancelamento; confira diagnóstico e situação da operação antes de repetir
REQUISICAO_EXCESSIVA, RESPOSTA_EXCESSIVA	Limite de bytes; reduza a carga dentro do contrato; não ultrapasse os tetos do cliente
FALHA_PIPE, FALHA_MOTOR, RESPOSTA_INVALIDA	Falha de comunicação ou protocolo; preserve resumo e evidência técnica sem segredos
ENCERRAMENTO_NAO_CONFIRMADO	O término do processo/threads não foi confirmado; não reutilize a instância
FALHA_EVENTO_ENVIO	O callback ao_iniciar_envio falhou; trate incerteza sem repetir automaticamente
CHAVE_INVALIDA, RECIBO_INVALIDO, PROTOCOLO_INVALIDO	Confira strings de 44/15 dígitos e a entrada tipada da operação
JUSTIFICATIVA_INVALIDA, INUTILIZACAO_INVALIDA	Confira bytes UTF-8 da justificativa e limites da faixa/ano/série
REDE_NAO_AUTORIZADA, CERTIFICADO_AUSENTE, RUNTIME_SEM_CAPACIDADE	Confira os bloqueios de rede das cinco operações remotas, A1 para assinatura/rede e capacidade específica da recuperação

O worker pode retornar outros valores em resultado.codigo. Registre o resumo do diagnóstico e consulte a fonte da operação; não trate a tabela como uma lista de todos os códigos fiscais.

Prazo e cancelamento

timeout é medido em segundos, até 120. O prazo abrange a execução/comunicação do processo filho. A verificação dos arquivos ocorre antes; encerramento e limpeza podem acrescentar tempo depois. Não prometa que o método retornará exatamente no valor de timeout.

O limite max_bytes vale para a requisição JSON completa e para o total de saída lida de stdout e stderr. XML de entrada e saída tem teto próprio de 4 MiB. Certificado e codificação base64 também ocupam espaço na requisição.

O cancelamento recebe um threading.Event. Não use uma variável booleana ou evento assíncrono diferente. Definir o evento solicita o encerramento da chamada; isso não desfaz uma consulta ou efeito já ocorrido no destino. O cliente encerra apenas o processo que criou para a operação.

Resultado incerto

Examine erro.resultado_desconhecido, erro.diagnostico.status_envio e erro.limpeza_confirmada. Após a criação do processo de transmitir, cancelar ou inutilizar, uma falha de transporte é tratada como incerta mesmo sem marcador de envio observado. A ausência de envio_iniciado não libera repetição. Em transmissão incerta, erro.xml_original pode conter o XML assinado original e deve permanecer fora de logs.

Também há resultados normais estado="INDETERMINADO" ou "PENDENTE", sem exceção, que exigem reconciliação. Um callback ao_iniciar_envio observa o marcador, mas não confirma aceitação nem persistência anterior ao envio. Se falhar ou bloquear, pode acrescentar incerteza; leia API.

Não interprete uma ausência de resposta como prova de que um destino remoto não recebeu nada. Preserve o estado da aplicação e siga o protocolo de reconciliação. Não acrescente retry automático a uma operação fiscal com resultado desconhecido.

TLS e HTTPS

Há dois contextos diferentes: o download Python do runtime e as conexões remotas feitas pelo worker nas operações com rede explícita. O download usa HTTPS e rejeita redirecionamentos para esquemas diferentes. Uma falha TLS no download pode aparecer como RUNTIME_DOWNLOAD_FALHOU.

Para diagnosticar, confira relógio do sistema, nome do destino, cadeia de confiança aprovada no ambiente e presença de proxy/interceptação TLS autorizado. No runtime, execute doctor e confira a compatibilidade do sistema e dos arquivos distribuídos. O cliente Python deste snapshot não oferece parâmetro público para CA, escolha de TLS ou bypass de verificação.

Não desative validação de certificado, não substitua HTTPS por HTTP e não altere bibliotecas ou openssl.cnf para contornar uma falha: a integridade é conferida por hash. O worker recebe ambiente mínimo e caminhos OpenSSL do próprio runtime; variáveis arbitrárias do processo pai não são automaticamente herdadas. Se a correção exigir nova configuração suportada, ela precisa ser implementada e validada no SDK/runtime antes de ser descrita como disponível.

Guia prático de TLS no Linux

Veja diagnóstico de TLS, raiz ICP-Brasil V10 e correção administrativa verificada. O guia distingue CA ausente, cadeia incompleta, relógio e proxy, explica a diferença entre Linux e Windows e identifica os runtimes auditados em PHP, Node e Python. Um resultado indeterminado continua exigindo reconciliação; corrigir o truststore não libera reenvio automático.