Webhook
Entenda o que é e como cadastrar um webhook para ser notificado das mudanças mais importantes sobre suas notas fiscais, com exemplos!
O que é Webhook?
Webhooks permitem que sistemas externos recebam notificações de todos os eventos que ocorrem na API.
Quando um evento acontece, a API envia uma requisição HTTP (POST) para a URL configurada no webhook com as informações relativas ao evento.
Ao receber a notificação, o sistema integrado a API pode executar diversas tarefas, dependendo do seu objetivo.
Eventos que notificam seu sistema:
Seu sistema será notificado sempre que uma nota fiscal mudar para um dos status abaixo:
• Autorizada - Nota fiscal foi autorizada pelo órgão responsável;
• Negada - Nota fiscal foi negada pelo órgão responsável;
• Cancelada - O cancelamento da nota fiscal foi autorizado pelo órgão responsável;
• CancelamentoNegado - O cancelamento da nota fiscal foi rejeitado pelo órgão responsável;
O valor em negrito representa o status que será retornado no parâmetro "nfeStatus".
Parâmetro "nfeMotivoStatus"
Este parâmetro só retorna diferente de null nos seguintes status:
• "nfeStatus": "Negada",
• "nfeStatus": "CancelamentoNegado",
{
"tipo": "NFS-e",
"empresaId": "string",
"nfeId": "string",
"nfeIdExterno": "string",
"nfeStatus": "string",
"nfeMotivoStatus": "string",
"nfeLinkPdf": "http://api.enotasgw.com.br/file/(...)/pdf",
"nfeLinkXml": "http://api.enotasgw.com.br/file/(...)/xml",
"nfeNumero": "string",
"nfeCodigoVerificacao": "string",
"nfeNumeroRps": "string",
"nfeSerieRps": "string",
"nfeDataCompetencia": "date"
}
Entenda o significado de cada atributo no Webhook:
• tipo
Tipo de nota fiscal que está sendo emitida.
• empresaId
Identificador da empresa associada à nota fiscal que gerou a notificação.
• nfeId
Identificador interno da nota fiscal no eNotas Gateway.
• nfeIdExterno
Identificador da nota fiscal definido pelo seu sistema no momento da emissão.
• nfeStatus
Status final em que se encontra a nota fiscal.
• nfeMotivoStatus
Razão pela qual a nota fiscal está com o status atual.
• nfeLinkPdf (Nota autorizada/cancelada)
Link público para o download PDF da nota fiscal.
• nfeLinkXml (Nota autorizada/cancelada)
Link público para o download XML da nota fiscal.
• nfeNumero
Número da nota fiscal no município.
• nfeCodigoVerificacao
Caso se aplique, representa o código de verificação na prefeitura.
• nfeNumeroRps
Representa o número de RPS (Recibo provisório de Serviço) da nota fiscal.
• nfeSerieRps
Representa a série da nota fiscal.
• nfeDataCompetencia
Data de competência da nota fiscal.
Como cadastrar o Webhook:
Pelo painel do eNotas Gateway acesse o menu Webhooks ➟ Novo webhook:
Entenda o significado de cada campo:
• Url
Insira neste campo o link direto para a página do seu sistema que será notificada;
• Content-Type
Escolha o formato que o Gateway deve utilizar para comunicar com seu sistema (JSON ou XML);
• Token
Se desejar, você pode especificar um token, ou seja, um código ou frase de sua preferência no cadastro de seu webhook.
Essa informação será enviada pelo Gateway em cada notificação para o seu link cadastrado, dessa forma, você consegue garantir que a requisição (POST) está realmente sendo enviada pelo eNotas Gateway.
O token de autenticação do webhook fica no cabeçalho da requisição, mais especificamente, no item "x-token".
Exemplo de envio de um token no headers
"headers": { "x-token": "Token webhook", "content-type": "application/json; charset=utf-8"}
Dados retornados na notificação:
Os dados do POST de notificação variam por tipo de nota fiscal.
Abaixo há o modelo de WEBHOOK para NFS-e.
Novas tentativas de envio em caso de falha
Se seu sistema apresentar instabilidades ou estiver fora do ar, o Gateway tentará lhe enviar o webhook de notificação até receber o status "HTTP 200", que indica que o webhook foi recebido e tratado com sucesso.
Serão realizadas 15 tentativas com intervalos de tempo progressivos entre cada uma delas, totalizando, em média, 4 horas.
Updated almost 3 years ago