Como simular erro de processamento na NFS-e
Antes de ir para produção, teste como sua integração reage a uma NFS-e rejeitada. O ambiente Development (ambiente de testes/sandbox da API de NFS-e) permite forçar esse cenário de forma controlada, sem depender de uma instabilidade real de prefeitura.
Pré-requisitos
- Inscrição Municipal da empresa com
Environment: "Development". - Número da Inscrição Municipal diferente dos números de teste reservados (por exemplo
355030999,111111,222222). Essas IMs reservadas são enviadas ao ambiente de testes da própria prefeitura e não passam por este comportamento. - Permissão para emitir NFS-e via API nesse ambiente.
Solução
No ambiente Development, quando o número da Inscrição Municipal não é um dos reservados, a nota é processada por um proxy genérico de testes. Esse proxy sempre aprova a nota — a menos que a descrição do serviço contenha o texto random error.
Com esse texto presente, o envio e a consulta do lote têm, cada um, cerca de 1 chance em 3 de falhar. O restante das chamadas é aprovado normalmente.
Etapa 1: Inclua "random error" na descrição do serviço
Ao montar o payload de emissão, adicione o texto random error (não diferencia maiúsculas/minúsculas) em algum ponto do campo de descrição do serviço.
{
"description": "Consultoria em TI - random error",
"servicesAmount": 100.00
}
Etapa 2: Envie a nota normalmente
Envie a requisição de emissão como faria em qualquer outro teste, com a IM em Development.
curl -X POST "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices" \
-H "Authorization: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"cityServiceCode": "0107",
"description": "Consultoria em TI - random error",
"servicesAmount": 100.00
}'
Etapa 3: Consulte o resultado
Consulte o status da nota (ou aguarde o webhook de atualização). Existe uma chance de a resposta indicar falha de processamento, com um destes códigos:
| Momento da falha | Código | Mensagem |
|---|---|---|
| Envio do lote (emissão) | E998 | Random error on SendBatch. |
| Consulta do lote (checagem de status) | E999 | Random error on CheckBatch. |
Se a nota não cair no cenário de erro, ela é aprovada normalmente, com número e protocolo simulados.
Variações
- Repita o teste várias vezes. Como o erro não ocorre em toda chamada, rode a emissão algumas vezes até observar a falha, se seu objetivo é validar o tratamento de erro.
- Combine com outros cenários de teste. Use
random errorjunto com os demais campos que você já testa (retenções, tomador estrangeiro, cliente não identificado) para verificar que o tratamento de erro não interfere no restante da regra de negócio. - Teste apenas o caminho de sucesso. Basta omitir
random errorda descrição — o proxy de testes sempre aprova a nota nesse caso.
Armadilhas comuns
- IM de teste reservada. Se o número da Inscrição Municipal é um dos reservados, a nota vai ao ambiente de testes da prefeitura e
random errornão tem efeito. - Tomador com CPF ou CNPJ inválido. O documento do tomador é validado antes do envio: um valor como
00000000000devolve400na hora e a nota nunca chega ao proxy de testes. Se precisar informar o tomador, use um CPF ou CNPJ válido — o tomador é opcional. - Esperar erro determinístico. O erro é probabilístico, não ocorre em 100% das chamadas. Não trate a ausência de erro na primeira tentativa como falha do teste.
- Usar em produção. Esse comportamento existe apenas no ambiente
Development. Descrições comrandom errorem produção são processadas normalmente pela prefeitura real, sem qualquer efeito especial.