Utilizando Webhooks

Adotar Webhooks em vez de consultas periódicas (polling) é a abordagem recomendada para o recebimento de atualizações de status. As principais vantagens dessa arquitetura orientada a eventos incluem:

• Processamento em Tempo Real: Notificações automáticas disparadas assim que o documento altera de status na SEFAZ ou prefeitura, permitindo reações imediatas da sua aplicação.
• Redução de Overhead no Servidor: Eliminação de requisições redundantes, reduzindo o consumo de CPU, I/O e banda em ambas as infraestruturas.
• Otimização de Quota (Rate Limit): Redução drástica no volume total de chamadas HTTP, eliminando o risco de esgotamento de quota ou bloqueios temporários (HTTP 429).

A API da Focus NF-e monitora a latência e a taxa de sucesso dos endpoints cadastrados para recebimento de webhooks. Servidores que respondem de forma rápida e consistente ganham prioridade nas nossas filas de disparo de eventos.

Boas Práticas de Implementação:

• Retorno Imediato (HTTP 200 ou 202): Responda à requisição do webhook imediatamente após validar a assinatura/payload, confirmando o recebimento.
• Processamento Assíncrono: Delegue as regras de negócio pesadas (escritas no banco de dados, envio de e-mails, etc.) para filas internas (background jobs ou workers), evitando reter a conexão do disparo da API.

Política de Retentativas de Webhook

Em caso de falha de conexão ou erro no seu endpoint, a API executa um fluxo automático de reenvio com intervalos progressivos (backoff) durante um período máximo de 48 horas.
Decorrido esse prazo sem sucesso na entrega, as tentativas são definitivamente encerradas. Como mecanismo de fallback, sua aplicação deverá realizar uma consulta direta (GET) ao endpoint do documento fiscal para obter e sincronizar o status atualizado.