Referência da API PHP

Referência derivada de src/ no commit documentado. Os modelos gerados estão em contrato; os formatos de chamadas fiscais estão em operações.

Emitter

new Acbr\Emitter(
    Configuration $configuration,
    ?string $runtimeDirectory = null,
    int $timeoutMs = 120000,
    int $maxBytes = 8388608,
    ?Engine $engine = null,
);

O runtime é resolvido e verificado ao executar a operação nativa, não ao construir o objeto. engine é uma fronteira de injeção explícita para testes offline ou integração própria; um mock não prova o comportamento nativo. O timeout aceito é de 1 a 120000 ms. maxBytes aceita 256 a 8388608 bytes e limita a requisição e a saída do transporte; não é o limite do XML individual.

Todas as nove operações retornam FiscalResult ou lançam erro. O segundo parâmetro opcional é ?callable $cancelled = null; uma função que devolva true solicita cancelamento cooperativo. No exemplo gerarXml($documento, cancelled: fn() => $cancelar), a variável precisa refletir o estado desejado; closures por valor não observam mudanças posteriores.

Método	Entrada principal	Necessita A1?	Rede fiscal com motor real?
gerarXml(Document|array $document, ?callable $cancelled = null)	Documento raiz TNFe validado	Não	Não
validar(string $xml, ?callable $cancelled = null)	XML UTF-8	Não	Não
assinar(string $xml, ?callable $cancelled = null)	XML UTF-8	Sim	Não
transmitir(string $xml, ?callable $cancelled = null)	XML assinado	Sim	Sim
consultar(array $data, ?callable $cancelled = null)	Chave e recibo opcional	Sim	Sim
recuperarXml(string $signedXml, ?callable $cancelled = null)	XML original assinado	Sim	Sim; somente modelo 55
cancelar(array $data, ?callable $cancelled = null)	Chave, protocolo, justificativa	Sim	Sim
cartaCorrecao(array $data, ?callable $cancelled = null)	Chave, correção, sequência	Sim	Sim; somente modelo 55
inutilizar(array $data, ?callable $cancelled = null)	Ano, série, faixa e justificativa	Sim	Sim
fechar(): void	Sem parâmetros	—	Não

Cada operação abre seu próprio processo worker. Não existe retry automático nem sessão nativa reutilizada. fechar() marca a instância como encerrada; novas operações lançam EMISSOR_FECHADO. Se a limpeza do processo não for confirmada, o emissor fecha permanentemente. Use try/finally e não faça chamadas síncronas concorrentes no mesmo emissor.

Configuração e segredos

new Configuration(
    string $cnpj, string $uf, int $modelo = 55, int $ambiente = 2,
    ?CertificateA1 $certificado = null, ?Csc $csc = null,
);
CertificateA1::fromData(string $pfx, string $password): CertificateA1;
CertificateA1::fromFile(string $path, string $password): CertificateA1;
new Csc(string $id, string $valor);

Configuration::hasCertificate() e hasCsc() retornam booleanos. Campos públicos cnpj, uf, modelo e ambiente são somente leitura; ler o CNPJ explicitamente é acesso a dado fiscal. JSON/debug omitem CNPJ e segredos. Veja segurança de A1 e CSC.

Document e modelos

new Document(array|stdClass $input = [], ?Contract $contract = null);
Document::fromArray(array $input, ?Contract $contract = null): static;
Document::fromJson(string $json, ?Contract $contract = null): static;
$documento->typeName(): string;
$documento->toArray(): array;
$documento->jsonSerialize(): stdClass;
$documento->toJson(int $flags = 0): string;
$documento->with(array $changes): static;
$documento->without(string ...$fields): static;
$documento->get(string $field): mixed;
$documento->has(string $field): bool;

Essas assinaturas descrevem métodos PHP; não são uma sequência copiável isoladamente. As classes de objeto geradas estendem Document e acrescentam getCampo()/withCampo(). A raiz gerada é Acbr\Model\TNFe. Propriedades diretas são recusadas para preservar imutabilidade. Veja modelos.

Contract

Contract::bundled(): Contract carrega o contrato versionado. A instância fornece metadata(): array, types(): array, type(string $name = 'TNFe'): array, fields(string $type = 'TNFe'): array, validate(mixed $value, string $type = 'TNFe', bool $strictObjects = false): void, normalize(mixed $value, string $type = 'TNFe'): mixed, help(string $query = 'TNFe'): array e formatHelp(string $query = 'TNFe'): string.

O construtor aceita ?string $path = null, mas exige revisão, hash e estrutura exatos do pin; não é uma abertura para um schema fiscal arbitrário. fields() só aceita tipos de objeto. A ajuda não precisa de runtime, certificado ou rede. Veja consultas de campos e tipos, incluindo Ide.tpNF e TTipoNFe. A CLI da alpha2 acrescenta sdkVersion ao seu envelope JSON; esse campo não altera o retorno de Contract::help(). describe TARGET mostra texto e describe TARGET --json ou ajuda TARGET retornam JSON.

FiscalResult e AcbrException

API de resultado	Retorno
sucesso(): bool	Flag devolvida pelo motor; não equivale isoladamente a autorização
estado(): string	Estado do protocolo
comando(): ?string	Operação associada pelo emissor
statusEnvio(): string	nao_enviado, autorizado, rejeitado, resultado_incerto
resultadoDesconhecido(): bool	Indica resultado_incerto
xml(): ?string	Acesso explícito ao XML decodificado, se presente
data(): array	Payload completo, potencialmente sensível
retornoOriginal(): array	Campos ACBr preservados no frame, quando disponíveis; acesso explícito e sensível
jsonSerialize(): array	Somente estado, códigos e classificação segura

AcbrException estende RuntimeException. Expõe propriedades somente leitura codigo: string, resultadoDesconhecido: bool, limpezaConfirmada: bool; tem xmlRecuperacao(): ?string para XML original disponível em falha de transmissão incerta e jsonSerialize(): array para diagnóstico redigido. Emitter::recuperarXml() usa o XML original assinado e uma consulta remota para obter um nfeProc validado no cenário suportado; não é download genérico por chave. Consulte resultados e recuperação.

Acbr\Model\ValidationException estende InvalidArgumentException, com codigo e campo. FieldHelpException tem codigo e candidates. Capture essas classes separadamente de AcbrException quando tratar entrada/help.

NativeRuntime, Engine e transporte

Para operação normal, prefira o emissor e a CLI do runtime. NativeRuntime::resolve(?string $directory = null) retorna runtime verificado, com directory (alias root), executable e manifest. environment() fornece o ambiente mínimo do filho. release() expõe o pin; diagnostics(?string $directory = null) verifica pré-requisitos e integridade sem iniciar o motor. install(string $source, ?string $destination = null) faz instalação não destrutiva do arquivo/diretório aceito.

Engine::execute(array $request, ?callable $cancelled = null): FiscalResult é a interface de testes. NativeEngine usa ProcessTransport, que valida JSONL, ID, revisão, hash, estado e tipos de resposta. Interfaces de baixo nível exigem que a aplicação respeite o protocolo e a sensibilidade dos dados; não substituem a validação de entrada do Emitter.

API assíncrona

Acbr\Async\AsyncEmitter expõe as mesmas nove operações e devolve Future, sem parâmetro público de callback de cancelamento. Oferece tick(int $waitMs = 0), drain() e fechar(). Future tem state(), isComplete(), cancel(), await() e result(). Requisitos, limites e OperationQueue estão em fila assíncrona.