Retentativas, Testes e Debug Local

Cronograma de 8 tentativas com backoff exponencial, timeout de 15s e teste com cloudflared.

Falhas transitórias de rede, deploys de aplicação e quedas temporárias de banco de dados são inevitáveis no mundo real. Para garantir que nenhuma notificação fiscal seja perdida, a NFER opera uma fila distribuída de alta resiliência baseada em BullMQ e Redis com política estrita de retentativas e monitoramento de entregas.

1. Cronograma de Retentativas (Backoff Exponencial)

Se o servidor receptor retornar erro 5xx, erro 429, erro 408 ou demorar mais de 15 segundos para responder, a NFER executa até 8 tentativas de entrega ao longo de mais de 2 horas:

Tentativa	Intervalo após falha	Tempo acumulado aproximado
1ª tentativa	Imediata (0s)	0s
2ª tentativa	+10 segundos	~10s
3ª tentativa	+30 segundos	~40s
4ª tentativa	+1 minuto	~1m 40s
5ª tentativa	+5 minutos	~6m 40s
6ª tentativa	+15 minutos	~21m 40s
7ª tentativa	+30 minutos	~51m 40s
8ª tentativa	+2 horas	~2h 51m

2. Curto-Circuito em Erros Não-Retentáveis (HTTP 4xx)

Para evitar desperdício de recursos e logs desnecessários, a NFER implementa curto-circuito inteligente:

Erros Definitivos (Encerra Imediatamente)

Respostas 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found e 422 Unprocessable indicam erro de configuração no receptor. As retentativas são interrompidas na 1ª falha.

Erros Transitórios (Aciona Fila de Retry)

Erros de servidor 500, 502, 503, 504, timeouts (>15s) e respostas de limite de taxa (429 Too Many Requests) seguem rigorosamente as 8 tentativas da tabela.

3. Testes e Reenvio Manual via API

POST/v1/webhooks/:id/test-connection

Dispara uma notificação imediata de ping/conectividade para a URL cadastrada.

POST/v1/webhooks/:id/test

Envia um evento fiscal real enfileirado para o webhook (requer eventType e nfeId).

GET/v1/webhooks/:id/deliveries

Lista as últimas entregas com código HTTP de retorno, tempo de resposta e payload.

POST/v1/webhooks/:id/deliveries/:deliveryId/retry

Reexecuta manualmente uma entrega com falha, mesmo após esgotadas as 8 tentativas.

DELETE/v1/webhooks/:id/deliveries

Limpa o histórico de logs de entregas registradas para o webhook.

Exemplo de Teste de Conectividade

curl -X POST "https://api.nfer.me/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test-connection" \

-H "Authorization: Bearer sec_live_sua_chave_secreta"

Exemplo de Simulação de Evento Fiscal Real

curl -X POST "https://api.nfer.me/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" \

-H "Authorization: Bearer sec_live_sua_chave_secreta" \

-H "Content-Type: application/json" \

-d '{

"eventType": "nfe.autorizada",

"nfeId": "e5b8d0c2-3e28-4f1b-8517-8e6d19a4e8d3"

A NFER busca os dados reais da nota informada e despacha o envelope completo com assinatura HMAC X-NFER-Signature.

4. Testando em Ambiente Local (localhost)

Como os servidores da NFER exigem uma URL HTTPS pública para despachar notificações, utilize ferramentas de tunelamento seguro durante o desenvolvimento local da sua aplicação:

Exemplo com Cloudflare Tunnel (Gratuito e sem limites):

cloudflared tunnel --url http://localhost:3000

Copie a URL HTTPS gerada (ex: https://sua-empresa.trycloudflare.com/webhooks/nfer) e cadastre no Dashboard ou via API em ambiente de homologação.