Saiba mais sobre WebHook, que são APIs de notificação que facilitam o acompanhamento de status das suas solicitações
O Plugnotas, conta com o recurso de API Callback, ou Webhook, também comumente conhecido como notificação, este recurso permite que nossa API chame uma rota de sua aplicação, sempre que determinada ação ocorrer.
Com este recurso, podemos trocar dados em tempo real entre nossas aplicações, te ajudando a automatizar suas tarefas. É enviada uma notificação para você, sempre que uma nota chegar a uma situação final (Concluído, Rejeitado, Cancelado, Denegado).
Quais os tipos de Webhook?
Contamos com dois contextos de Webhook, Software House, onde todas as notificações das empresas vinculadas serão disparadas para um único endpoint, ou no contexto da empresa, sendo possível cadastrar um endpoint diferente para cada.
Exemplo Software House: Tenho 2 empresas emitindo pelo PlugNotas, cada uma delas autorizou 1 nota, meu endpoint configurado será acionado 2 vezes.
2 vezes -> https://minhaapi.com.br/notificacoes/
Exemplo empresa: Tenho 2 empresas emitindo pelo Plugnotas, cada uma delas autorizou 1 nota, como cada Empresa possuí o seu endpoint, enviaremos uma requisição para cada.
Uma vez: https://minhaapi.com.br/notificacoes/08187168000160
Uma vez: https://minhaapi.com.br/notificacoes/08892365602165
Rota para o contexto de Software House:
https://api.plugnotas.com.br/webhook
Rota para o contexto de empresa:
https://api.plugnotas.com.br/empresa/{cnpj}/webhook
Quando serei notificado?
- Notifica ao Concluir: Informa que a nota foi processada e está com status final de CONCLUÍDO;
- Notifica ao Cancelar: Informa que a nota está com status final de CANCELADO;
- Notifica ao Rejeitar: Informa que a nota foi processada e REJEITADO.
- Notifica ao Denegar: Informa que a nota foi processada e DENEGADO pela Sefaz.
O Webhook é disparado sempre que a nota atinge uma situação final, ou transita de uma situação final para outra.
Ex: PROCESSANDO para CONCLUIDO ou CONCLUIDO para CANCELADO.
O que eu preciso para utilizar a integração por webhook?
- Em sua API, crie um endpoint (rota) que aceite uma requisição POST, PATCH, ou PUT.
- Caso sua aplicação processe corretamente nossa mensagem (SUCESSO), essa rota precisa devolver um Status Code 200.
- Em caso de falha do processamento de nossa mensagem (ERRO), essa rota precisa devolver um Status Code que não pertença à família do 2xx, como, por exemplo, um 500.
- Cadastre seu endpoint em /webhook ou /empresa/{cnpj}/webhook.
Tentaremos reenviar a requisição para a sua API diversas vezes, em intervalos regulares, até que o limite de tentativas seja excedido (~ 6 horas), ou que sua API retorne um Status Code 2xx.
Cadastrando um webhook
Método: POST
URL: https://api.plugnotas.com.br/webhook
Body:
RESPOSTA
Em caso de sucesso, vamos retornar um Status Code 200, com o seguinte conteúdo:
Exemplos de conteúdo de Webhook para NFS-e
O conteúdo de nosso Webhook, é baseado em nossa rota de consulta resumida, respeitando o mesmo schema, apenas adicionando o campo documento para facilitar sua identificação.
Exemplo de nota CONCLUÍDO:
Exemplo de nota REJEITADO:
Exemplo de nota CANCELADO:
Exemplos de conteúdo do Webhook para NF-e e NFC-e
O conteúdo de nosso Webhook, é baseado em nossa rota de consulta resumida, respeitando o mesmo schema, apenas adicionando o campo documento para facilitar sua identificação.
Obs: o campo “documento” (primeiro que aparece no json de retorno), vai vir com o valor “nfce”, quando for emitida uma NFC-e
Exemplo de nota CONCLUÍDO:
Exemplo de nota REJEITADO:
Exemplo de nota CANCELADO:
Importante saber:
- O webhook é sempre individual, mesmo que envie um lote de 50 notas, você receberá 50 notificações individualmente;
- Notas com status PROCESSANDO, não disparam o webhook;
- Se necessário, libere o IP 54.144.48.129 e 3.210.19.145 para o correto recebimento das notificações.
Agora que você já conhece mais uma das inteligências do Plugnotas, pode focar seu tempo e esforço nos requisitos mais importantes do seu projeto.
A demanda dos documentos fiscais eletrônicos pode ser muito complexa, desafiadora e difícil, mas você não precisa enfrentar essa missão sozinho.
Fale com um dos nossos consultores para saber mais detalhes, teremos o prazer em atendê-lo.
