Operações fiscais e parâmetros

Os nove métodos abaixo existem na alpha2 documentada, com o mesmo contrato da alpha1. Geração, assinatura e schema têm evidência offline do projeto; chamadas de rede têm testes automatizados simulados/HTTPS local. As fontes separam um roteiro pessoal histórico de homologação NF-e 55; os exemplos deste site não executam operações fiscais remotas. Consulte resultados antes de interpretar uma resposta.

Todos os exemplos desta página mostram formatos de API; os identificadores repetidos são sintéticos e não devem ser enviados a um serviço fiscal. operacoes-mock.php cobre os oito métodos anteriores, e recuperar-xml-mock.php demonstra a recuperação separadamente. Ambos usam Engine injetada, sem rede. Todos os exemplos usam ambiente 2.

Gerar XML

$resultado = $emissor->gerarXml($documento);

Aceita Document, TNFe ou array raiz. A estrutura é normalizada contra o contrato antes da requisição; campos omitidos não recebem defaults PHP. Não exige certificado e não envia nota. Acesse o XML por $resultado->xml() após avaliar sucesso(). Veja primeiro XML.

Validar XML

$resultado = $emissor->validar($xml);

Executa validação nativa com os schemas do runtime. Não exige A1 nem comunica a SEFAZ. Um documento sem assinatura pode ser rejeitado pelo schema que exige XMLDSig. Validação de schema não comprova cadastro, regras tributárias completas ou autorização.

Assinar XML

$resultado = $emissor->assinar($xml);
$xmlAssinado = $resultado->sucesso() ? $resultado->xml() : null;

Exige A1 configurado. Para NFC-e, configure também CSC adequado ao fluxo. A assinatura acontece no worker; não autoriza a nota nem verifica, por si só, confiança ICP-Brasil e revogação. Use certificado sintético apenas no fluxo local de teste; veja A1 seguro.

Transmitir

$resultado = $emissor->transmitir($xmlAssinado);

Exige A1 e faz chamada de rede com motor real, inclusive em homologação. Não há modo de simulação implícito. Antes da chamada, a aplicação precisa guardar com segurança a intenção, chave, XML assinado, modelo, ambiente e identidade do emissor; depois, persistir o retorno/protocolo de forma durável.

Uma conexão interrompida ou um timeout pode ocorrer depois que a SEFAZ recebeu o pedido. Não retransmita automaticamente. O retorno pode ser FiscalResult incerto ou uma exceção com resultadoDesconhecido=true; siga recuperação.

Consultar

$resultado = $emissor->consultar([
    'chave' => str_repeat('1', 44), // SOMENTE ilustração sintética
    'recibo' => str_repeat('2', 15), // omita se não existir
]);

chave é string de exatamente 44 dígitos. recibo, quando presente, é string de 15 dígitos; não envie null. A operação exige A1 e rede, mas não tem efeito de autorização/envio por si mesma. Uma resposta “não localizado” isolada não prova que uma tentativa anterior pode ser reenviada com segurança. O SDK não oferece distribuição DF-e nem download genérico de XML por chave.

Recuperar XML

recuperarXml(string $signedXml, ?callable $cancelled = null) recebe a NF-e modelo 55 original assinada, exige A1 e faz consulta com o motor real. Não retransmite. Sucesso requer XML_RECUPERADO com cStat=100 e provas coerentes; o worker valida a montagem do nfeProc. Veja contrato, limites e exemplo somente mock. Esta página não fornece comando para recuperação fiscal real.

Cancelar

$resultado = $emissor->cancelar([
    'chave' => str_repeat('1', 44),
    'protocolo' => str_repeat('2', 15),
    'justificativa' => 'JUSTIFICATIVA SINTETICA DE TESTE LOCAL',
]);

Chave de 44 dígitos, protocolo de 15 dígitos, justificativa UTF-8 com 15 a 255 bytes. As regras de prazo/aceitação pertencem ao serviço fiscal e devem ser verificadas pela aplicação. A chamada tem efeito fiscal quando recebida; cancelar execução local não desfaz um cancelamento já recebido.

Carta de correção

$resultado = $emissor->cartaCorrecao([
    'chave' => str_repeat('1', 44),
    'correcao' => 'CORRECAO SINTETICA PARA EXEMPLO LOCAL',
    'sequenciaEvento' => 1,
]);

Somente NF-e modelo 55. A chave tem 44 dígitos; correção UTF-8 de 15 a 1000 bytes. sequenciaEvento é inteiro de 1 a 20 e assume 1 quando omitido. A aplicação deve controlar a sequência e a admissibilidade da correção; não aplique retry cego que gere evento duplicado.

Inutilizar faixa

$resultado = $emissor->inutilizar([
    'ano' => 26,
    'serie' => 1,
    'numeroInicial' => 1,
    'numeroFinal' => 2,
    'justificativa' => 'JUSTIFICATIVA SINTETICA DE TESTE LOCAL',
]);

Campo	Tipo e limite PHP
ano	Inteiro 0 a 99
serie	Inteiro 0 a 999
numeroInicial	Inteiro de 1 até o número final
numeroFinal	Inteiro até 999999999, maior ou igual ao inicial
justificativa	String UTF-8, de 15 a 255 bytes

O Emitter recebe campos planos e monta internamente inutilizacao para o protocolo; não passe um grupo inutilizacao diretamente a esse método. Controle a faixa de forma durável e confirme a resposta fiscal.

Regras comuns

• XML precisa ser string UTF-8 não vazia com até 2097152 bytes (2 MiB). O SDK o codifica em base64 internamente; não envie base64 no parâmetro público.
• Campos extras nos arrays de operações são rejeitados por OPERACAO_INVALIDA.
• Identificadores fiscais são strings; ano, série, números da faixa e sequência são inteiros. Não há coerção automática.
• Textos têm limites em bytes, iguais aos do motor Pascal; caracteres acentuados podem ocupar mais de um byte.
• Todas as operações aceitam callback de cancelamento cooperativo na API síncrona.
• A1 ausente em assinar/transmitir/consultar/recuperarXml/cancelar/cartaCorrecao/inutilizar gera CERTIFICADO_AUSENTE antes do worker.

Não existem nesta revisão danfe, imprimir, A3, distribuição DF-e ou configuração para ignorar TLS. Consulte limitações e FAQ.