Pular para o conteúdo principal

Explicando e cadastrando Webhook/API Callback

Leticia Pessoa
Atualizado

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. Enviaremos uma notificação para você, sempre que uma nota chegar a uma situação final (Concluído, Rejeitado, Cancelado, Denegado).

Separamos essa documentação por tópicos para facilitar sua leitura, siga em ordem, ou vá direto ao tópico de seu interesse.

 

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/29062609000177

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 CONCLUIDO;
  • 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 Interromper: Informa que a nota foi INTERROMPIDA.

O webhook é disparado sempre que a nota atinge uma situação final, transita de uma situação final para outra ou quando o evento de cancelamento é REJEITADO. Ex: PROCESSANDO para CONCLUIDO ou CONCLUIDO para CANCELADO.

Para eventos de Carta de Correção, o webhook é disparado quando o status final se encontrar como REJEITADO ou CONCLUIDO.

 

O que eu preciso para utilizar a integração por webhook?

  1. Em sua API, crie um endpoint (rota) que aceite uma requisição POST, PATCH, ou PUT.
  2. Caso sua aplicação processe corretamente nossa mensagem (SUCESSO), essa rota precisa devolver um Status Code 200.
  3. 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.
  4. 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 

{
  "url": "Aqui você informa seu endpoint",
  "method": "POST"
}

RESPOSTA

Em caso de sucesso, vamos retornar um Status Code 200, com o seguinte conteúdo: 

{
  "message": "Operação realizada com sucesso"
} 

 

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 CONCLUIDO:

{
"id": "5ecbbaabbdbd4670e36b9999",
"idIntegracao" : "XXX999",
"emissao": "25/05/2020",
"tipoAutorizacao": "WEBSERVICE",
"situacao": "CONCLUIDO",
"prestador": "85511318000190",
"tomador": "08114280956",
"valorServico": 60,
"numeroNfse": "266",
"serie": "1",
"lote": 58370,
"numero": 22263,
"codigoVerificacao": "LVYTBX2WTF3",
"autorizacao": "25/05/2020",
"mensagem": "RPS Autorizada com sucesso",
"pdf": "https://api.plugnotas.com.br/nfse/pdf/5ecbbaabbdbd4670e36b9999",
"xml": "https://api.plugnotas.com.br/nfse/xml/5ecbbaabbdbd4670e36b9999",
"documento": "nfse"
}

Exemplo de nota REJEITADO:

{
"id": "5ecbc124f3333719851ba999",
"idIntegracao" : "XXX999",
"emissao": "25/05/2020",
"tipoAutorizacao": "WEBSERVICE",
"situacao": "REJEITADO",
"prestador": "85511318000190",
"tomador": "08114280956",
"valorServico": 110.8,
"serie": "1",
"mensagem": "Certificado vencido em: 23/05/2020 00:25:25, atualize seu certificado digital para continuar emitindo.",
"documento": "nfse"
}

Exemplo de nota CANCELADO:

{
"id" : "5ecbc124f3333719851ba999",
"idIntegracao" : "XXX999",
"emissao" : "29/12/2020",
"tipoAutorizacao" : "WEBSERVICE",
"situacao" : "CANCELADO",
"prestador" : "85511318000190",
"tomador" : "08114280956",
"valorServico" : 60,
"numeroNfse" : "000024175",
"serie" : "1",
"lote" : 58370,
"numero" : 22263,
"codigoVerificacao" : "PKZA35766",
"autorizacao" : "29/12/2020",
"mensagem" : "Cancelamento de NFS-e Homologado",
"pdf" : "https://api.plugnotas.com.br/nfse/pdf/5ecbc124f3333719851ba999",
"xml" : "https://api.plugnotas.com.br/nfse/xml/5ecbc124f3333719851ba999",
"cancelamento" : "30/12/2020",
"documento" : "nfse"
}

Exemplo de nota INTERROMPIDO:

{
"id": "5ecbc124f3333719851ba999",
"emissao": "02/07/2024",
"tipoAutorizacao": "WEBSERVICE",
"situacao": "INTERROMPIDO",
"prestador": "85511318000190",
"tomador": "75623990000113",
"valorServico": 0.5,
"emailSolicitanteInterrupcao": "teste@teste.com.br",
"dataInterrupcao": "02/07/2024 15:20:40 (Horário de Brasília)",
"mensagem" : "Interrupção de NFS-e realizada com sucesso. Aguarde alguns instantes caso precise sincronizar.",
"documento": "nfse"
}

Existe também a possibilidade de um webhook de retorno completo, para isto basta configurar o webhook com o parâmetro nfse.retornoCompleto trazendo assim todos os dados da nota detalhadamente, o json da notificação possui o mesmo layout trazido na rota de consulta completa de NFS-e.

 

Exemplos de conteúdo do Webhook para NF-e, NFC-e e NFCom

 

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 CONCLUIDO:

{
"id": "61af61d0b33ac8369c0e9084",
"idIntegracao": "testeweb",
"emissao": "07/12/2021",
"status": "CONCLUIDO",
"destinada": false,
"emitente": "85511318000190",
"destinatario": "08114280956",
"valor": 4.6,
"dataAutorizacao": "07/12/2021",
"numero": "600388",
"serie": "805",
"chave": "41211229062609000177558050006003881614635110",
"protocolo": "141210001176277",
"mensagem": "Autorizado o uso da NF-e",
"xml": "https://api.plugnotas.com.br/nfe/61af61d0b33ac8369c0e9084/xml",
"pdf": "https://api.plugnotas.com.br/nfe/61af61d0b33ac8369c0e9084/pdf",
"cStat": 100,
"documento": "nfe"
}

Exemplo de NFCom CONCLUIDO:

{
  "id": "690bb2f65ca1fbcfbb8a6150",
  "idIntegracao": "nfcom-webhook",
  "emissao": "04/11/2025",
  "status": "CONCLUIDO",
  "emitente": "29062609000177",
  "destinatario": "11111111111",
  "valor": "10.00",
  "dataAutorizacao": "05/11/2025",
  "numero": "49",
  "serie": "1",
  "chave": "43251129062609000177620010000000000000000000",
  "protocolo": "1111111111111111",
  "mensagem": "Autorizado o uso da NFCom ",
  "cStat": 100,
  "xml": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/xml",
  "pdf": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/pdf",
  "documento": "nfcom"
}

 

Exemplo de nota REJEITADO:

{
 "documento": "nfe",
 "id" : "998646d10dc724d738bef599",
  "idIntegracao": "testeweb",
 "codigo" : "99999",
 "emissao" : "02/04/2020",
 "status" : "REJEITADO",
 "emitente" : "85511318000190",
 "destinatario" : "29062609000177",
 "valor" : 2143.7,
 "numero" : "831",
 "serie" : "1",
 "chave" : "31200425710000000460550010000008311131009999",
 "mensagem" : "Rejeicao: Total do Desconto difere do somatorio dos itens",
 "xml": "https://api.plugnotas.com.br/nfe/61af61d0b33ac8369c0e9084/xml",
 "pdf": "https://api.plugnotas.com.br/nfe/61af61d0b33ac8369c0e9084/pdf",
 "cStat": 537
}

 

Exemplo de NFCom REJEITADO: 

{
  "id": "690bb2f65ca1fbcfbb8a6150",
  "idIntegracao": "nfcom-webhook",
  "emissao": "30/10/2025",
  "status": "REJEITADO",
  "emitente": "29062609000177",
  "destinatario": "11111111111",
  "valor": "1642.78",
  "numero": "49",
  "serie": "1",
  "chave": "43251129062609000177620010000000000000000000",
  "mensagem": "Rejeição: Falha no schema XML [The element 'imposto' in namespace..
  "mensagemError": "Falha na comunicação com o webservice",
  "cStat": 215,
  "xml": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/xml",
  "documento": "nfcom"
}

 

Exemplo de nota CANCELADO (NF-e):

{
"documento": "nfe",
"id": "5f99e7f54283fe3c5a67b65c",
"idIntegracao": "XXX999",
"emissao": "28/10/2020",
"status": "CANCELADO",
"destinada": false,
"emitente": "85511318000190",
"destinatario": "08114280956",
"valor": 9.2,
"numero": "1000008",
"serie": "805",
"chave": "41201029062609000177558050010000081705343099",
"protocolo": "141200000952447",
"dataAutorizacao": "28/10/2020",
"mensagem": "Evento registrado e vinculado a NF-e",
"xml": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/xml",
"xmlCancelamento": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/cancelamento/xml",
"pdf": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/pdf",
"dataCancelamento": "28/10/2020",
"protocoloCancelamento": "141200000952462",
"cStat": 135
}

 

Exemplo de nota CANCELADO (NFC-e):

{
  "id": "5f99e7f54283fe3c5a67b65c",
  "idIntegracao": "XXX999",
  "emissao": "28/10/2020",
  "status": "CANCELADO",
  "emitente": "85511318000190",
  "destinada": false,
  "destinatario": "08114280956",
  "valor": 9.2,
  "numero": "1000008",
  "serie": "805",
  "chave": "41201029062609000177658050010000081705343099",
  "protocolo": "141200000952447",
  "dataAutorizacao": "28/10/2020",
  "mensagem": "Evento registrado e vinculado a NF-e",
  "pdf": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/pdf",
  "xml": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/xml",
  "cancelamento": {
    "cStat": 135,
    "date": "2020-10-28T14:52:31.064Z",
    "protocolo": "230100000841353",
    "respostaSefaz": "Evento registrado e vinculado a NF-e",
    "status": "CONCLUIDO"
  },
  "xmlCancelamento": "https://api.plugnotas.com.br/nfe/5f99e7f54283fe3c5a67b65c/cancelamento/xml",
  "dataCancelamento": "28/10/2020",
  "cStat": 135,
  "documento": "nfe"
}

Exemplo de nota CANCELADO (NFCom): 

{
  "id": "690bb2f65ca1fbcfbb8a6150",
  "idIntegracao": "nfcom-webhook",
  "emissao": "04/11/2025",
  "status": "CANCELADO",
  "emitente": "29062609000177",
  "destinatario": "11111111111",
  "valor": "10.00",
  "dataAutorizacao": "05/11/2025",
  "dataCancelamento": "05/11/2025",
  "protocoloCancelamento": "1111111111111111",
  "numero": "49",
  "serie": "1",
  "chave": "43251129062609000177620010000000000000000000",
  "protocolo": "1111111111111111",
  "mensagem": "Cancelamento realizado com sucesso.",
  "cStat": 135,
  "xml": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/xml",
  "xmlCancelamento": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/cancelamento/xml",
  "pdf": "https://api.plugnotas.com.br/nfcom/690bb2f65ca1fbcfbb8a6150/pdf",
  "documento": "nfcom"
}

Exemplo de Cancelamento Rejeitado:

{
"id": "61af61d0b33ac8369c0e9084",
"idIntegracao": "testeweb",
"emissao": "07/12/2021",
"status": "CONCLUIDO",
"destinada": false,
"emitente": "85511318000190",
"destinatario": "08114280956",
"valor": 4.6,
"cancelamento": {
      "justificativa": "Cancelamento por conta de nota emitida com CNPJ fornecedor incorreto",
      "cStat": 501,
      "date": "2025-02-12T14:05:46.569Z",
      "respostaSefaz": "Prazo de cancelamento superior ao previsto na Legislacao",
      "status": "REJEITADO"
      },
"documento": "nfe"
}

 

 

Observações

  • 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;
  • Uma nota quando autorizada, será mudada de status PROCESSANDO para CONCLUIDO. Posteriormente, iremos gerar o pdf e xml e assim que tivermos sucesso na geração dos arquivos, iremos então notificar a conclusão da nota via WEBHOOK. Será possível visualizar que a nota está com o status CONCLUÍDO por meio da rota de consulta, mesmo antes do envio do webhook.
  • Se necessário, libere os IP's 54.144.48.129 e 3.210.19.145 para o correto recebimento das notificações.

 

Artigos relacionados

Comentários

0 comentário

Por favor, entre para comentar.