Perguntas frequentes

Posso instalar pelo PyPI?

Sim. A alpha 0.1.0a5 está publicada: python -m pip install "acbr-python==0.1.0a5". O import é acbr. Veja a instalação por plataforma.

Preciso de Node.js, npm, PHP, Django ou Flask?

Não. O cliente usa a biblioteca padrão Python e inicia o executável Pascal/ACBr diretamente, com JSON por stdin/stdout. Os arquivos nativos conservam o nome e a proveniência de sua distribuição de origem, ACBr Node; isso não exige executar JavaScript nem instalar npm. Aplicações de qualquer framework podem compor essa integração, desde que controlem concorrência, ciclo de vida e persistência. Veja runtime e licenças.

Como descubro os valores de Ide.tpNF?

Na versão publicada a5, execute python -m acbr describe Ide.tpNF --json para o campo ou python -m acbr ajuda TTipoNFe para seu tipo. A saída JSON informa tnEntrada e tnSaida; somente o campo declara o padrão tnSaida. A API describe_field oferece a mesma consulta em Python, e python -m acbr --help mostra os comandos disponíveis. Tudo isso funciona offline, sem runtime ou A1. Consulte a ajuda integrada.

Posso usar describe na versão instalada pelo PyPI?

Sim. A alpha 0.1.0a5 oferece describe em texto em português, describe --json, python -m acbr --version e describe_type. ajuda TARGET continua retornando JSON. Esses recursos novos não existem na a3; confira a versão instalada com python -m acbr --version e siga a ajuda integrada.

Quais operações estão disponíveis?

Na versão publicada 0.1.0a5: gerar_xml, validar, assinar, transmitir, consultar, cancelar, inutilizar e recuperar_xml experimental. Assinatura é local e exige A1; todas as operações de rede exigem A1 e allow_network=True por chamada. A implementação não equivale a homologação fiscal; a evidência de rede é simulada.

sucesso=True significa autorização?

Depende da etapa. gerar_xml com XML_GERADO significa geração local; validar com VALIDADO significa validação local. A recuperação experimental só aceita sucesso em seu contrato específico de XML processado. Confira API.

Documento({}) é aceito. Isso é uma nota válida?

Não. O contrato confere a forma dos campos presentes e permite omissões. Regras fiscais e obrigatoriedade de schema não são implementadas pelo validador Python. Consulte contrato.

Por que valores monetários são strings?

Para preservar a representação decimal do contrato e evitar perda de precisão de float. Use "10.00", ponto decimal e a escala permitida. Não use 10.0, "10,00" ou notação científica.

O XML recém-gerado pode falhar na validação?

Sim. O schema pode exigir assinatura; gerar_xml não assina. Uma validação negativa retornada corretamente comprova comunicação com o motor, mas não sucesso fiscal do documento.

Posso usar Linux Alpine, ARM, macOS ou Python 32 bits?

Não estão no alvo do MVP. O runtime exige Windows x64 ou Linux x64/glibc com Python x64. Ubuntu 24.04 é a referência Linux, sem promessa automática de compatibilidade com toda distribuição.

doctor chama a SEFAZ?

Não. Ele verifica localmente plataforma, proveniência, inventário e hashes. Não executa o motor. Ajuda e validação estrutural também não fazem chamada fiscal.

Posso compartilhar um emissor entre threads?

Uma instância aceita uma operação por vez; concorrência gera EMISSOR_OCUPADO, sem fila. Coordene agendamento na aplicação. Para fluxos assíncronos, isole o trabalho bloqueante com limites explícitos; não há API async pública neste snapshot.

Timeout ou cancelamento autorizam repetir?

Não automaticamente. Eles não provam que um destino remoto não recebeu a chamada. Guarde os dados originais, leia o diagnóstico e reconcilie. Não há retry ou rollback automático.

Como corrijo erro TLS?

Verifique relógio, nome do destino, cadeia de confiança e integridade do runtime. Não há parâmetro de bypass TLS nesta API. Siga o guia de falhas; não desative a verificação de certificados.

ao_iniciar_envio confirma autorização ou impede duplicidade?

Não. O callback recebe EventoEnvio(id, comando) quando o cliente observa o marcador do worker em transmissão, cancelamento ou inutilização. Não há garantia de persistência anterior ao envio, autorização, aceitação ou idempotência. Falha no callback pode deixar resultado incerto. Veja API e recuperação.

Posso consultar somente pelo recibo?

Não neste runtime. Consulta sempre exige uma chave de 44 dígitos, mesmo quando recebe um recibo opcional de 15 dígitos.

Posso registrar to_wire() para depurar?

Não em logs comuns: configuração inclui certificado, senha e CSC, e documento inclui carga fiscal. Use os resumos de ResultadoFiscal.to_dict() e AcbrError.diagnostico.to_dict(), revisando qualquer dado adicional.

Como acompanho versões e propostas de mudança?

Compare o pacote instalado com a tag v0.1.0a5. As fontes exatas e os limites de validação estão em fontes. Revalide exemplos ao atualizar a biblioteca; propostas futuras só devem ser tratadas como disponíveis após a publicação correspondente.

Uma falha TLS no Linux pode afetar PHP, Node e Python?

Sim, nos runtimes auditados a conexão fiscal é do worker Pascal/OpenSSL. Linux e Windows consultam fontes de confiança diferentes; uma raiz ausente no bundle Linux pode afetar os três clientes naquele ambiente. Isso não comprova a causa de uma tentativa anterior sem retorno original preservado. Consulte o guia de TLS no Linux, com fontes oficiais, fingerprint, diagnóstico e procedimento que exige aprovação administrativa.