RoboFiscalOperação técnica e resolução de problemas
Como meu sistema fica sabendo que uma nota foi autorizada ou rejeitada?
Cadastre um webhook no RoboFiscal para receber eventos como nota autorizada, rejeitada ou cancelada. Seu endpoint deve validar a assinatura, registrar a entrega com segurança e responder rapidamente. Processe o trabalho posterior em fila e reconheça reentregas pelo identificador. Mantenha também consultas de conciliação: uma notificação pode atrasar ou exigir nova tentativa.
Fatos e fontes
- A RFC 2104 descreve HMAC como mecanismo de autenticação de mensagens com chave compartilhada.Fonte: IETF: RFC 2104, autenticação HMAC.
- A RFC 9110 define o significado das respostas HTTP usadas para confirmar requisições.Fonte: IETF: RFC 9110, semântica HTTP.
- A LGPD prevê proteção contra acesso não autorizado aos dados pessoais tratados.Fonte: Planalto: Lei 13.709/2018, arts. 6º e 46.
- A API nacional disponibiliza consultas e eventos para acompanhar documentos fiscais.Fonte: Portal NFS-e: manual da API, v1.2.
- O RoboFiscal assina webhooks e mantém um identificador de entrega estável nas retentativas.Fonte: RoboFiscal: contrato OpenAPI público.
Nesta página
Como validar que o evento veio do RoboFiscal?
Leia X-Robofiscal-Timestamp e X-Robofiscal-Signature. Calcule HMAC-SHA256 sobre timestamp, ponto e corpo bruto da requisição, usando o segredo do webhook. Compare a assinatura em tempo constante e aplique uma janela de validade ao timestamp. A serialização do JSON não deve ser refeita antes da verificação, pois isso altera os bytes assinados.
Como responder sem perder processamento?
Depois de validar, grave duravelmente o identificador e o evento, ou confirme que aquela entrega já foi registrada. Responda 2xx após esse registro e processe as ações seguintes em uma fila. Não espere geração de PDF ou chamadas a outros serviços para responder ao webhook. Se o registro falhar, não confirme uma entrega que será perdida.
Como tratar eventos repetidos ou fora de ordem?
Use X-Robofiscal-Entrega para reconhecer a mesma entrega. Confira a nota antes de aplicar uma mudança que possa substituir um estado mais recente. Exemplo: uma notificação de autorização recebida com atraso não deve fazer seu sistema esquecer um cancelamento já confirmado. Consulte a API quando houver divergência.
mensagem = timestamp + "." + corpoBruto
assinaturaEsperada = "sha256=" + HMAC_SHA256(segredo, mensagem)
compararEmTempoConstante(assinaturaRecebida, assinaturaEsperada)Passo a passo
- Cadastre uma URL HTTPS e guarde o segredo no servidor.
- Valide assinatura sobre o corpo bruto e confira o timestamp.
- Registre a entrega de forma durável e idempotente.
- Responda rapidamente e processe o trabalho posterior em fila.
- Monitore falhas e concilie a situação das notas pela API.
Erros comuns
- Reformatar o JSON antes de verificar a assinatura.
- Responder sucesso antes de guardar o evento ou repetir efeitos a cada retentativa.
Como o RoboFiscal ajuda
O RoboFiscal oferece eventos de notas e acompanhamento de entregas pela API. O receptor precisa validar a mensagem e controlar seu próprio processamento para evitar perda ou repetição de ações.
Consulte eventos, autenticação e tentativas de entrega antes de cadastrar a integração.
Perguntas relacionadas
O segredo do webhook é a chave de API?
Trate-os como credenciais de finalidades diferentes: a chave autentica chamadas à API e o segredo verifica as notificações.
Posso usar só webhooks, sem consultas?
Mantenha consultas de conciliação para falhas, atrasos e divergências de estado.
Continue lendo
Revisado em · Equipe RoboFiscal. Versão em texto