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

Envia um evento simulado de teste para a URL cadastrada.

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.

Exemplo de Disparo de Teste

curl -X POST "https://api.nfer.me/v1/webhooks/whk_01HXYZ7890ABCDEF/test" \

-H "Authorization: Bearer sec_live_sua_chave_secreta"

A NFER envia um payload com "event": "webhook.test" e retorna o status HTTP retornado pelo seu servidor e o tempo em milissegundos.

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.