Recuperação de XML e resultados incertos

Disponível desde a alpha1, a API inclui Emitter::recuperarXml(string $signedXml, ?callable $cancelled = null): FiscalResult. A operação recebe a NF-e original assinada, usa A1 e faz consulta de rede com o motor real. Não gera, assina nem retransmite a nota. Esta página explica o contrato; seu exemplo executável usa somente um motor simulado, sem rede ou certificado real.

AcbrException::xmlRecuperacao() é outra API: acesso explícito ao XML original de uma transmissão incerta, quando preservado pelo transporte. Ela não consulta a SEFAZ nem devolve automaticamente um XML autorizado.

Contrato e limites de recuperarXml

Aspecto	Limite mantido na alpha2/runtime 0.2.1
Entrada	XML original assinado da NF-e, UTF-8, não vazio, até 2 MiB
Modelo	NF-e 55; não é recuperação NFC-e 65
Identidade	Chave, emissor, ambiente e digest precisam corresponder ao documento e ao protocolo
Resposta de sucesso	XML_RECUPERADO, sucesso=true, cStat=100, chave de 44 e protocolo de 15 dígitos
XML recuperado	nfeProc validado pelo worker, UTF-8, até 4 MiB; assinatura original preservada
Envio	envioIniciado=false: não houve envio fiscal, mas houve consulta de rede
Outros retornos	Inclusive cStat=150: CONSULTADO, sucesso=false, RECUPERACAO_NAO_COMPROVADA, sem XML de sucesso

O worker valida assinatura/schema/identidade e compõe o nfeProc com o protocolo obtido. Não basta entregar uma chave ou montar um XML qualquer: a API não aceita chave, recibo ou protocolo separados. Protocolos de 17 dígitos, protocolos/eventos adicionais não suportados e assinatura adicional no protocolo são recusados. Estados contraditórios geram RESPOSTA_INVALIDA.

consultar() conserva seu contrato anterior e não passa a baixar XML. A recuperação não é distribuição DF-e nem um download genérico por chave. A API assíncrona correspondente é AsyncEmitter::recuperarXml(string $signedXml): Future; o cancelamento usa o Future.

Exemplo completo sem rede

O arquivo recuperar-xml-mock.php injeta uma Engine que retorna uma resposta sintética. A configuração permanece em HOMOLOGAÇÃO, o XML não tem valor fiscal e nenhum worker é iniciado. Ele demonstra o formato da chamada, os acessos explícitos ao resultado e a classificação local; não comprova validação de assinatura/schema nem recuperação fiscal real.

php examples/recuperar-xml-mock.php

Use o bootstrap e os exemplos na raiz de uma aplicação Composer ou configure ACBR_PHP_AUTOLOAD. Não substitua a Engine simulada por um motor real para transmitir as fixtures.

Protocolo após timeout ou transmissão incerta

1. Antes de uma operação com efeito fiscal, persista de forma durável a intenção, ambiente, modelo, chave e XML assinado original. O SDK não fornece armazenamento durável nem idempotência remota.
2. Em falha, consulte resultadoDesconhecido e limpezaConfirmada da exceção; um FiscalResult também pode conservar resultado_incerto.
3. Bloqueie o retry automático da intenção enquanto faltar prova. Timeout, TLS e cancelamento local não desfazem uma recepção remota já ocorrida.
4. Preserve o XML original sob controle de acesso. xmlRecuperacao() pode ser null, inclusive após encerramento forçado; não é substituto de sua persistência anterior.
5. Reconcilie pelo fluxo apropriado e correlacione chave, modelo, ambiente, emissor, estado e protocolo com a intenção. recuperarXml() cobre o cenário delimitado acima; outros eventos e faixas exigem sua própria prova.
6. Uma consulta isolada “não localizado”, um retorno intermediário ou uma duplicidade não autoriza reenvio. Mantenha o estado incerto até haver prova suficiente.

O exemplo recuperacao-mock.php conserva a simulação de timeout e consulta, inteiramente em memória. A aplicação ainda precisa implementar persistência, programação de consultas e correlação do resultado; nenhum desses exemplos é uma transação durável completa.

Resultado original e dados sensíveis

FiscalResult::xml() devolve o XML decodificado presente no frame. retornoOriginal(): array expõe origem=frame_nativo e os campos disponíveis, como cStat, xMotivo, chave, protocolo, recibo, xmlBase64 e xmlDecodificado. Na recuperação, retornoWebServiceOriginalDisponivel=false informa que o SOAP/RetWS bruto não foi exportado. O acesso não consulta novamente e não inventa campos ausentes.

data(), xml() e retornoOriginal() são acessos explícitos a dados potencialmente sensíveis. O JSON/debug padrão conserva somente o diagnóstico seguro. Guarde XML e protocolo em armazenamento privado, sem expô-los em logs ou telas públicas.

Não componha um nfeProc inventando protocolo, data ou código a partir de timeout. A classificação autorizado da recuperação exige o retorno coerente implementado e ainda precisa ser correlacionada com a intenção da aplicação. Veja resultados e erros.

Fontes fixas: API e limitações da recuperação, Emitter e FiscalResult.