API pública Python

Referência da versão 0.1.0a5 publicada no PyPI, commit dc0f2bba9927, tag v0.1.0a5. A implementação permanece alpha e sem homologação fiscal.

Exportações e ciclo de vida

O pacote acbr exporta Emissor, Configuracao, CertificadoA1, Csc, Documento, Consulta, Cancelamento, Inutilizacao, EventoEnvio, ResultadoFiscal, Diagnostico, AcbrError, describe_field, describe_type e validate_document.

Metadados de campos e tipos

describe_field(path: str) -> dict está disponível desde a a3: aceita nome exato de tipo, caminho de campo ou nome curto não ambíguo. Retorna uma cópia independente dos metadados do contrato, sem runtime, A1 ou rede. Exemplo:

from acbr import describe_field

campo = describe_field("Ide.tpNF")
assert campo["values"] == ["tnEntrada", "tnSaida"]
assert campo["declaredDefault"] == "tnSaida"

describe_type(name: str) -> dict, disponível a partir da a4, consulta estritamente um nome de tipo; um caminho como Ide.tpNF gera TIPO_INVALIDO. A CLI publicada também oferece describe TARGET, describe TARGET --json e --version. Consulte o guia integrado de ajuda para exemplos e códigos de saída. Esses recursos não alteram a validação fiscal nem as oito operações abaixo.

Construção e encerramento do emissor

from collections.abc import Callable
from pathlib import Path
from acbr import Configuracao, Emissor, EventoEnvio

# Assinatura de referência:
# Emissor(config: Configuracao, *, runtime_directory: Path | str,
#         timeout: float = 120, max_bytes: int = 8 * 1024 * 1024,
#         ao_iniciar_envio: Callable[[EventoEnvio], None] | None = None)

config = Configuracao(cnpj="00000000000000", uf="CE", modelo=55, ambiente=2)
with Emissor(config, runtime_directory=Path(".runtime/runtime"), timeout=30) as emissor:
    pass  # Somente construção; nenhuma operação é iniciada aqui.

runtime_directory é o diretório exato retornado pelo instalador, normalmente destino/runtime. timeout aceita número finito maior que zero e até 120 segundos. max_bytes aceita inteiro entre 256 e 8 MiB. O limite vale para o JSON enviado e para o total de stdout/stderr lido.

Use o context manager ou fechar() -> None. O fechamento solicita término do processo pertencente à chamada e impede reutilização. Uma instância executa uma operação por vez: concorrência produz EMISSOR_OCUPADO, sem fila implícita. Não há cliente async público, pool ou persistência embutida.

Entradas de operações

Tipo	Campos	Verificação estrutural
Documento(dados)	Dicionário TNFe	Contrato de campos e tipos; não aplica regras fiscais
Consulta(chave, recibo=None)	Chave e recibo opcional	Chave obrigatória com 44 dígitos; recibo opcional com 15
Cancelamento(chave, protocolo, justificativa)	Identificação e motivo	Chave com 44 dígitos; protocolo com 15; justificativa 15–255 bytes UTF-8
Inutilizacao(ano, serie, numero_inicial, numero_final, justificativa)	Ano, série, faixa e motivo	Ano 0..99; série 0..999; 1 <= inicial <= final <= 999999999; justificativa 15–255 bytes UTF-8

Chaves, protocolos e recibos são strings de dígitos ASCII, preservando zeros à esquerda; não há cálculo de dígitos verificadores. Os números de inutilização são inteiros exatos, sem booleanos. Ano é o valor de dois dígitos, como 26, não 2026. Justificativa tem limite em bytes UTF-8, não em quantidade de caracteres.

Os métodos consultar, cancelar e inutilizar exigem exatamente suas dataclasses; dicionários e subclasses não substituem essas entradas. Nenhum construtor comprova prazo legal, titularidade, autorização anterior ou elegibilidade fiscal.

from acbr import Consulta, Cancelamento, Inutilizacao

consulta = Consulta(chave="0" * 44, recibo="0" * 15)
cancelamento = Cancelamento(
    chave="0" * 44, protocolo="0" * 15,
    justificativa="TESTE SINTETICO SEM VALOR FISCAL",
)
inutilizacao = Inutilizacao(
    ano=26, serie=1, numero_inicial=1, numero_final=1,
    justificativa="TESTE SINTETICO SEM VALOR FISCAL",
)
# Apenas construção de exemplos sintéticos. Não os envie a serviços fiscais.

Consulta sempre exige chave, inclusive com recibo: o runtime fixado 0.2.1, que preserva o worker da 0.2.0, não oferece consulta apenas por recibo.

Assinaturas dos oito métodos

Todos retornam ResultadoFiscal; cancel aceita threading.Event | None, com padrão None.

Método	Entrada e parâmetros nomeados	Rede e certificado
gerar_xml	(documento: Documento | dict, *, cancel=None)	Local; sem A1 obrigatório
validar	(xml: str, *, cancel=None)	Local; sem A1 obrigatório
assinar	(xml: str, *, cancel=None)	Local; exige A1
transmitir	(xml_assinado: str, *, allow_network=False, cancel=None)	Exige A1 e rede explícita
consultar	(consulta: Consulta, *, allow_network=False, cancel=None)	Exige A1 e rede explícita
cancelar	(cancelamento: Cancelamento, *, allow_network=False, cancel=None)	Exige A1 e rede explícita
inutilizar	(inutilizacao: Inutilizacao, *, allow_network=False, cancel=None)	Exige A1 e rede explícita
recuperar_xml	(xml_assinado: str, *, allow_network=False, cancel=None)	Experimental; exige A1 e rede explícita

Os cinco métodos remotos exigem literalmente allow_network=True a cada chamada. A omissão, 1 ou outro valor gera REDE_NAO_AUTORIZADA antes de iniciar o worker. HOMOLOGAÇÃO (ambiente=2) também usa rede real. O bloqueio padrão é demonstrado pelos exemplos offline.

XML deve ser exatamente str, UTF-8 válido, não vazio e até 4 MiB. O cliente não modifica a identidade fiscal para combinar com a configuração. Todas as operações verificam integridade antes de iniciar o runtime; cancelamento já solicitado e falta de A1 são tratados antes da execução.

gerar_xml produz XML local. assinar assina usando o A1 configurado e não transmite. validar usa validação nativa local: XML sem assinatura pode falhar no schema. transmitir recebe XML já assinado, não assina automaticamente e usa o comportamento síncrono/uma tentativa do worker fixado. Não há opção pública de lote, modo assíncrono ou retry. cancelar e inutilizar podem produzir efeitos fiscais reais quando a rede é habilitada.

Resultados e estados

Atributo de ResultadoFiscal	Significado
sucesso: bool	Conclusão segundo o estado da etapa; não significa autorização genérica
estado	Estado tipado e conferido com a resposta do worker
diagnostico: Diagnostico	Código, etapa, mensagem, ação e status_envio
codigo: str | None	Código textual retornado pelo worker
c_stat: int | None	cStat fiscal quando houver
chave, protocolo, recibo	Identificadores opcionais e sensíveis
xml_base64 / propriedade xml	Conteúdo opcional; acesso explícito ao XML decodificado
x_motivo	Mensagem bruta opcional; avaliar privacidade antes de registrar
envio_iniciado: bool	Marcador observado; ausência não prova ausência de envio
retorno_original	Cópia privada do frame JSON validado do worker, ou None; pode conter dados sensíveis
origem_retorno_original	"acbr_worker_jsonl" quando há frame, ou None

Estados locais de sucesso são XML_GERADO, ASSINADO e VALIDADO. Operações fiscais podem produzir AUTORIZADO, CANCELADO, INUTILIZADO, DENEGADO, REJEITADO, PENDENTE, CONSULTADO ou INDETERMINADO, conforme comando e resposta. recuperar_xml tem contrato específico de XML_RECUPERADO; veja recuperação.

Não deduza autorização por sucesso=True. Por exemplo, uma consulta com cStat=217 produz CONSULTADO, sucesso verdadeiro e status_envio="nao_autorizado". Uma consulta autorizada pode retornar sem XML. O estado PENDENTE inclui códigos 103, 104, 105, 108, 109, 204, 539 e 573; exige reconciliação antes de repetir.

Um retorno normal INDETERMINADO, com sucesso=False, também exige reconciliação. Em transmissão indeterminada, resultado.xml contém o XML original, não um XML autorizado. Confira o estado antes de persistir conteúdo como documento processado.

resultado.to_dict() contém somente sucesso, estado e o diagnóstico resumido. repr omite campos sensíveis; acessos explícitos continuam sendo responsabilidade da aplicação. Não registre XML, chave, protocolo, recibo, carga completa, PFX, senha ou CSC em logs comuns.

Desde a a3, retorno_original preserva por acesso explícito os campos do JSONL validado, inclusive campos adicionais entregues pelo worker. Não é SOAP bruto da SEFAZ, uma nova consulta ou um comprovante independente. Cada acesso retorna uma cópia; campos que não chegaram continuam ausentes. dataclasses.asdict(resultado) inclui campos privados e não serve como resumo seguro de log; prefira to_dict().

ao_iniciar_envio e EventoEnvio

O callback síncrono ao_iniciar_envio(evento) recebe EventoEnvio(id, comando) imutável quando o cliente observa o marcador do worker em transmitir, cancelar ou inutilizar. O ID da requisição é gerado como UUID hexadecimal; o evento não inclui XML ou dados fiscais.

O callback roda em uma thread daemon própria, dentro do prazo da operação. Seja rápido; corrotinas não são aguardadas e o valor retornado é ignorado. Uma exceção vira FALHA_EVENTO_ENVIO, sem expor detalhes da exceção do consumidor. Um callback bloqueado pode continuar após o timeout e impedir a confirmação de limpeza.

O evento observa o envio; não o autoriza, não confirma aceitação, não cria idempotência e não garante persistência anterior ao envio remoto. Não use o callback como transação de banco ou prova de que nada foi enviado quando ele não chegou.

Exceções, cancelamento e incerteza

Falhas de validação/fiscais podem retornar sucesso=False sem exceção. AcbrError representa falhas de entrada, rede, integridade, execução e protocolo. Expõe codigo, resultado_desconhecido, diagnostico, limpeza_confirmada e xml_original opcional. Desde a a3, também pode preservar retorno_original e origem_retorno_original por acesso explícito, com a mesma origem JSONL e os cuidados de privacidade descritos acima. Um frame preservado pode coexistir com falha de transporte ou limpeza não confirmada; não elimina a incerteza.

Após criar o processo de transmitir, cancelar ou inutilizar, uma falha de transporte é tratada como incerta mesmo sem marcador de envio observado. Em transmissão incerta, erro.xml_original pode preservar o XML assinado original por acesso explícito. Ele não aparece no diagnóstico ou repr; a aplicação deve preservar sua própria cópia antes da chamada.

Cancelamento e timeout encerram apenas o processo pertencente à chamada, não fazem rollback remoto nem repetição automática. Leia erros, timeout e TLS e reconciliação antes de integrar operações remotas.

Superfícies que não são oferecidas

Não há método público de carta de correção, distribuição DF-e, consulta somente por recibo, cofre A1, fila, deduplicação persistente ou API assíncrona. O nome camelCase recuperarXml pertence ao protocolo interno; o método Python é recuperar_xml. A CLI oferece somente ajuda, instalação do runtime e doctor, sem comandos fiscais.