Perguntas frequentes e limitações

O pacote está pronto para produção?

O estado documentado é 0.1.0-alpha2, uma pré-release. Há testes automatizados offline/simulados e um relato histórico de roteiro pessoal específico em homologação NF-e 55. Isso não certifica todos os cenários, produção nem a correção tributária do consumidor. Consulte fontes e validação.

Posso instalar com um nome do Packagist?

Sim. A pré-release 0.1.0-alpha2 está publicada como cosmemilton/acbr-php. Use composer require cosmemilton/acbr-php:0.1.0-alpha2, preserve o lock e confira a referência. Veja instalação. A versão do SDK é independente do runtime 0.2.1.

Funciona em Windows?

Não no SDK PHP fixado. O motor Windows do projeto Node é outra distribuição; não habilita suporte PHP automaticamente. Use um ambiente Linux x64/glibc previamente disponível e validado, ou aguarde implementação e testes específicos. ARM, macOS, 32 bits e Alpine/musl também não têm suporte.

Preciso de Node, npm, Delphi ou ACBr Pro?

Não para executar esse cliente. PHP conversa com o processo Free Pascal separado. A distribuição foi empacotada no formato npm, mas o instalador recebe um arquivo local e não executa npm/scripts. O pacote não é oficial do Projeto ACBr.

Posso usar Laravel ou Symfony?

Sim, o cliente é independente de framework. A integração, configuração segura, persistência e tratamento de resultado ficam no consumidor. A matriz do projeto cobriu CLI; valide sua execução web/job. A fila opcional com fork() é somente CLI Linux e não deve herdar conexões abertas pelo framework.

Como descubro os valores de um campo ou enum?

Consulte Contract::bundled()->help('Ide.tpNF') ou help('TTipoNFe'); ambos mostram tnEntrada/tnSaida. formatHelp() produz texto em português. A ajuda é offline e não requer o motor. Na alpha2 instalada, use php vendor/bin/acbr-php describe Ide.tpNF para texto ou describe TTipoNFe --json/ajuda TTipoNFe para JSON. --version mostra a versão do SDK. A alpha1 conserva a API PHP e os exemplos, mas não possui esses comandos CLI. Veja ajuda de campos e tipos.

Por que 10.00 precisa ser string?

O contrato preserva decimais sem coerção de float. Use '10.00', com ponto e escala permitida pelo campo. Inteiros de enum ou strings numéricas para campos int não são convertidos automaticamente.

XML gerado e schema válido significa autorizado?

Não. São etapas locais. Assinatura também não é autorização. Uma confirmação precisa de estado, operação, código, chave e protocolo coerentes, além da correlação com a intenção da aplicação; veja resultados.

Posso transmitir os exemplos em homologação?

Não transmita a fixture sintética desta documentação. Ela serve para testes offline. Ambiente 2 é homologação, mas uma chamada remota ainda é uma operação fiscal real. Os exemplos de chamadas fiscais usam Engine simulada justamente para manter os dados fictícios locais.

Há DANFE, impressão, PDF ou A3?

Não há comandos correspondentes no motor fixado. Um campo de tipo de impressão no XML não cria renderizador. O certificado aceito é A1 PFX/P12; não existe configuração de token/cartão ou PKCS#11 para A3 nessa API.

Existe recuperarXml ou download de XML por chave?

Existe recuperarXml($xmlOriginalAssinado) na alpha1, para NF-e modelo 55. Usa o XML original assinado, consulta e valida a montagem do nfeProc; não é distribuição DF-e nem download genérico por chave. O fluxo exige A1 e rede com motor real. Os exemplos desta documentação usam somente mock. Veja recuperação e limites. AcbrException::xmlRecuperacao() continua sendo um acesso separado ao XML original de uma transmissão incerta.

Uma consulta “não localizado” permite reenviar?

Isoladamente, não. A resposta pode não dar prova final sobre uma tentativa anterior. A revisão trata esse resultado de forma conservadora. Preserve a intenção como incerta e siga o procedimento fiscal aplicável antes de qualquer nova tentativa.

Timeout, TLS ou cancelamento garantem que nada foi enviado?

Não. O erro pode ocorrer depois da recepção remota. Leia as flags de erro, preserve o XML original e confirme a situação. Não há retry automático nem opção documentada para desligar TLS. Corrija a causa sem enfraquecer a validação da conexão.

O runtime passou em verify, mas não executa. Por quê?

Verificação confere integridade e inventário, não compatibilidade da glibc/carregador nem execução. O diagnóstico deixa nativeExecutionChecked: false. Confira plataforma, permissões e testes offline no destino. Não copie bibliotecas extras para o inventário verificado.

Posso apontar para o symlink current do deploy?

Não para o caminho do runtime PHP. O verificador rejeita links, inclusive ancestrais. Passe a pasta física da versão instalada e mantenha logs fora dela. Esse limite do runtime não dita como um site estático de documentação organiza seus arquivos.

O que não vem pronto no SDK?

Cadastro e tributação do consumidor, banco de documentos, armazenamento seguro de segredos, fila durável, idempotência remota, reconciliação completa de todos os eventos, gestão de contingência, distribuição DF-e, renderização de DANFE e homologação fiscal. Não apresente composição da aplicação como se fosse método nativo existente.

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.