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": "29062609000177",
"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": "29062609000177",
"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" : "29062609000177",
"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": "29062609000177",
"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"
}

 

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

{
"id": "61af61d0b33ac8369c0e9084",
"idIntegracao": "testeweb",
"emissao": "07/12/2021",
"status": "CONCLUIDO",
"destinada": false,
"emitente": "29062609000177",
"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 nota REJEITADO:

{
 "documento": "nfe",
 "id" : "998646d10dc724d738bef599",
  "idIntegracao": "testeweb",
 "codigo" : "99999",
 "emissao" : "02/04/2020",
 "status" : "REJEITADO",
 "emitente" : "29062609000177",
 "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 nota CANCELADO:

{
"documento": "nfe",
"id": "5f99e7f54283fe3c5a67b65c",
"idIntegracao": "XXX999",
"emissao": "28/10/2020",
"status": "CANCELADO",
"destinada": false,
"emitente": "29062609000177",
"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
}

 

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;
• Se necessário, libere os IP's 54.144.48.129 e 3.210.19.145 para o correto recebimento das notificações.