Erros, TLS, timeout e cancelamento

Separe três situações: entrada estrutural recusada, falha operacional do SDK/transporte e resultado fiscal retornado pelo motor. Uma rejeição fiscal pode ser um FiscalResult; uma exceção pode deixar o efeito fiscal desconhecido.

use Acbr\AcbrException;
use Acbr\Model\ValidationException;

try {
    $resultado = $emissor->gerarXml($documento);
    if (!$resultado->sucesso() || $resultado->resultadoDesconhecido()) {
        $resumoSeguro = $resultado->jsonSerialize();
        // Registrar só os campos seguros na observabilidade da aplicação.
    }
} catch (ValidationException $erro) {
    $resumoSeguro = $erro->jsonSerialize(); // código e caminho, sem valor enviado
} catch (AcbrException $erro) {
    $resumoSeguro = $erro->jsonSerialize();
    if ($erro->resultadoDesconhecido) {
        // Bloquear repetição automática e iniciar reconciliação fiscal.
    }
    if (!$erro->limpezaConfirmada) {
        // Encerrar o uso deste processo PHP; o emissor não será reutilizado.
    }
} finally {
    $emissor->fechar();
}

Os comentários acima indicam decisões da aplicação; o SDK não cria banco, fila durável ou reconciliação automática. Veja o exemplo completo sem rede.

Erros de documento e help

Código representativo	Causa e correção
JSON_INVALIDO	JSON/UTF-8/profundidade inválida; conferir entrada original de forma privada
CAMPO_DESCONHECIDO	Nome fora do contrato; consultar fields() e help
CAMPO_SOMENTE_LEITURA	Campo de saída informado como entrada
ENUM_INVALIDO	String não coincide com enum versionado
DECIMAL_INVALIDO	Usar string decimal com ponto e escala correta, não float
DATA_HORA_INVALIDA / DATA_INVALIDA	Data civil inválida, offset ou Z; não há conversão automática de fuso
OBJETO_ESPERADO / ARRAY_ESPERADO	Tipo ou distinção JSON {}/[] incorreta
CAMPO_AMBIGUO	Help curto combina vários grupos; usar caminho completo dos candidates
COLECAO_REQUER_INDICE	Incluir [] ao percorrer item de coleção

ValidationException e FieldHelpException não herdam de AcbrException. O help não executa o motor, portanto uma falha nele não representa envio fiscal.

Erros de configuração e parâmetros

CONFIGURACAO_INVALIDA, CERTIFICADO_AUSENTE, CERTIFICADO_INVALIDO, CERTIFICADO_EXCESSIVO, CSC_INVALIDO, XML_INVALIDO, CHAVE_INVALIDA, RECIBO_INVALIDO, PROTOCOLO_INVALIDO, JUSTIFICATIVA_INVALIDA, CORRECAO_INVALIDA, INUTILIZACAO_INVALIDA, OPERACAO_INVALIDA e OPERACAO_NAO_SUPORTADA indicam configuração ou entrada recusada pela biblioteca. Confira os limites de A1/CSC e operações. Não faça retry de entrada inválida sem corrigi-la.

Erros de runtime e transporte

Código	Verificação recomendada
RUNTIME_ALTERADO	Conferir pin e origem; reinstalar em nova pasta a partir do artefato confiável
CONTRATO_DIVERGENTE	Biblioteca, contrato e runtime precisam ser a combinação exata
RUNTIME_LINK_INVALIDO	Usar caminho físico sem links, inclusive ancestrais
RUNTIME_INCOMPLETO / RUNTIME_ARQUIVO_EXTRA	Restaurar inventário exato; logs fora do runtime
RUNTIME_NAO_EXECUTAVEL	Conferir permissão e plataforma sem alterar o pin
RUNTIME_DESTINO_EXISTENTE	Escolher novo destino, sem substituir instalação em uso
PROC_OPEN_INDISPONIVEL	Verificar política do PHP no processo autorizado
FALHA_INICIAR_MOTOR	Conferir executável, carregador/glibc e permissões
REQUISICAO_EXCESSIVA / RESPOSTA_EXCESSIVA	Conferir tamanho do payload e limites de bytes; base64 também ocupa espaço
RESPOSTA_INVALIDA / FALHA_PIPE / FALHA_MOTOR	Protocolo, saída truncada ou processo interrompido; avaliar incerteza antes de repetir
TIMEOUT_MOTOR	Prazo expirado após iniciar comunicação; conferir flags e recuperar situação fiscal

Uma mensagem livre do motor pode conter contexto sensível. Prefira o código e os indicadores seguros; não publique stderr bruto, traces ou payloads em tickets públicos.

Timeout e encerramento

Emitter(timeoutMs: 10000) define dez segundos para a comunicação depois de proc_open; a verificação prévia do runtime fica fora desse prazo. O valor máximo é 120000 ms. Verificação de arquivos, escalonamento e tentativa limitada de encerramento podem aumentar o tempo total observado.

O transporte usa pipes não bloqueantes e drena stderr, limita bytes e valida ID/revisão/hash/estado antes de aceitar resposta. Em falha, tenta encerrar apenas o processo que pertence à chamada. Nenhuma API de espaço de usuário garante matar um processo bloqueado no kernel. Se não confirmar a limpeza, expõe limpezaConfirmada=false e fecha o emissor; interrompa o uso desse processo PHP e encaminhe a análise operacional sem sinalizar processos alheios.

Cancelamento cooperativo

$resultado = $emissor->gerarXml(
    $documento,
    cancelled: static fn(): bool => connection_aborted() !== 0,
);

O callback é verificado antes e durante a comunicação. Pode lançar OPERACAO_CANCELADA. Cancelamento local não desfaz um evento recebido pela SEFAZ; uma operação ativa com efeito pode continuar classificada como incerta. Na fila, Future::cancel() solicita interrupção do trabalho e não equivale ao evento fiscal cancelar().

Diagnóstico de TLS sem enfraquecer a conexão

O transporte HTTP/TLS remoto pertence ao motor e às bibliotecas do runtime fixado. O SDK PHP não oferece um parâmetro para desligar validação TLS ou alterar arbitrariamente os módulos. Não use curl -k, verify_peer=false, troca de HTTPS por HTTP nem patch de pin para contornar falhas.

Em erro TLS, registre de forma privada código, etapa, horário, ambiente/UF e versão exata. Confirme relógio do sistema, validade/cadeia do A1 autorizado, disponibilidade do endpoint correto e compatibilidade das bibliotecas da distribuição fixada. Um teste do curl do sistema não prova que o OpenSSL incorporado ao motor tem o mesmo comportamento. Preserve licenses/, módulos OpenSSL, configurações e inventário; dependências faltantes não devem ser “corrigidas” copiando arquivos extras para o runtime.

Se a correção exigir alteração do motor/runtime, trate-a como atualização revisada e testada separadamente. Mesmo um erro TLS não autoriza assumir que nada foi processado: consulte resultadoDesconhecido, statusEnvio() e o protocolo de recuperação. Esta página não atesta que um teste fiscal remoto específico foi aprovado.

Guia prático de TLS no Linux

Veja diagnóstico de TLS, raiz ICP-Brasil V10 e correção administrativa verificada. O guia distingue CA ausente, cadeia incompleta, relógio e proxy, explica a diferença entre Linux e Windows e identifica os runtimes auditados em PHP, Node e Python. Um resultado indeterminado continua exigindo reconciliação; corrigir o truststore não libera reenvio automático.