O que é Webhook?
É uma forma de notificar em tempo real outro sistema quando algum evento é disparado.
Exemplo de aplicação de Webhook
Uma aplicação desenvolvida com tecnologia server-side(PHP), onde os clientes acessam o site a partir dos computadores pessoais ou de sua loja, não consegue ler os retornos de processamento do NS SAT, por uma limitação de segurança.
Sabendo da importância da leitura e tratamento dos retornos de processamento, possibilitamos a utilização de webhooks para emissão e cancelamento, onde é cadastrado um endpoint para a respectiva finalidade e quando o evento ocorre, é enviado um json para a url.
Formatos de Entrada
Retorno de Emissão
O webhook do retorno de emissão é acionado após o processamento de um CF-e no NS SAT, havendo um webhook com finalidade RETEMISSAO, é enviado um json no formato abaixo para o endpoint informado:
| Campo | Descrição | Observação |
|---|---|---|
| emitente | CNPJ do emitente do CF-e | |
| identificador | Identificador informado na linha B durante a emissão | Retornado apenas se informado na emissão |
| cStat | Código de retorno do SAT | |
| xMotivo | Descrição do retorno | |
| dhAutorizacao | Data de autorização do CF-e | Apenas quando CF-e for autorizado |
| chave | Chave do CF-e | Apenas quando CF-e for autorizado |
| qrCode | QR Code do CF-e | Apenas quando CF-e for autorizado |
| xml | XML de distribuição do CF-e | Apenas quando CF-e for autorizado |
| erro | Descrição do erro no processamento | Apenas quando ocorrer erro no processamento |
Retorno de Cancelamento
O webhook do retorno de cancelamento é acionado após o processamento de um cancelamento de CF-e no NS SAT, havendo um webhook com finalidade RETCANC, é enviado um json no formato abaixo para o endpoint informado:
| Campo | Descrição | Observação |
|---|---|---|
| emitente | CNPJ do emitente do CF-e a ser cancelado | |
| cStat | Código de retorno do SAT | |
| xMotivo | Descrição do retorno | |
| chave | Chave do CF-e | |
| dhAutorizacao | Data de autorização do cancelamento do CF-e | Apenas quando cancelamento for autorizado |
| qrCode | QR Code do CF-e | Apenas quando cancelamento for autorizado |
| xml | XML de distribuição do cancelamento do CF-e | Apenas quando cancelamento for autorizado |
| erro | Descrição do erro no processamento | Apenas quando ocorrer erro no processamento |
Resposta esperada
Como resposta, o webhook do NS SAT espera um status HTTP 200 (ok), sem necessidade de uma resposta no body.