Eventos para notas fiscais

É possível utilizar Webhooks para que seu sistema seja notificado sobre alterações que ocorram nas notas fiscais.

Os eventos de nota fiscal permitem acompanhar todo o ciclo de emissão, sincronização, autorização, cancelamento e tratamento de falhas das notas fiscais emitidas através do Asaas.

Os eventos que o Asaas notifica são:

INVOICE_CREATED - Geração de nova nota fiscal.
INVOICE_UPDATED - Alteração na nota fiscal.
INVOICE_SYNCHRONIZED - Nota fiscal enviada para a prefeitura.
INVOICE_AUTHORIZED - Nota fiscal emitida.
INVOICE_PROCESSING_CANCELLATION - Nota fiscal processando cancelamento.
INVOICE_CANCELED - Nota fiscal cancelada.
INVOICE_CANCELLATION_DENIED - Recusado o cancelamento da nota fiscal.
INVOICE_ERROR - Nota fiscal com erro.

Quando utilizar

Os Webhooks de notas fiscais são recomendados quando sua aplicação precisa acompanhar automaticamente o status das notas fiscais emitidas pelo Asaas.

Alguns exemplos de utilização:

disponibilizar o PDF da nota fiscal para o cliente;
armazenar XML da nota fiscal em sistemas externos;
acompanhar autorizações e cancelamentos;
atualizar ERP ou sistema próprio;
identificar erros de emissão;
executar integrações fiscais automatizadas.

Fluxo dos eventos

O ciclo de uma nota fiscal normalmente segue o fluxo:

Nota fiscal criada
↓
INVOICE_CREATED
↓
Envio para prefeitura
↓
INVOICE_SYNCHRONIZED
↓
Nota autorizada
↓
INVOICE_AUTHORIZED

Caso ocorra alguma alteração:

Nota alterada
↓
INVOICE_UPDATED

Em caso de cancelamento:

Solicitação de cancelamento
↓
INVOICE_PROCESSING_CANCELLATION
↓
INVOICE_CANCELED

Caso a prefeitura recuse o cancelamento:

INVOICE_CANCELLATION_DENIED

Em caso de erro:

INVOICE_ERROR

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "INVOICE_CREATED",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "invoice": {
        "object": "invoice",
        "id": "inv_000000000232",
        "status": "SCHEDULED",
        "customer": "cus_000000002750",
        "type": "NFS-e",
        "statusDescription": null,
        "serviceDescription": "Nota fiscal da Fatura 101940. \nDescrição dos Serviços: ANÁLISE E DESENVOLVIMENTO DE SISTEMAS",
        "pdfUrl": null,
        "xmlUrl": null,
        "rpsSerie": null,
        "rpsNumber": null,
        "number": null,
        "validationCode": null,
        "value": 300,
        "deductions": 0,
        "effectiveDate": "2018-07-03",
        "observations": "Mensal referente aos trabalhos de Junho.",
        "estimatedTaxesDescription": "",
        "payment": "pay_145059895800",
        "installment": null,
        "taxes": {
            "retainIss": false,
            "iss": 3,
            "cofins": 3,
            "csll": 1,
            "inss": 0,
            "ir": 1.5,
            "pis": 0.65
        },
        "municipalServiceCode": "1.01",
        "municipalServiceName": "Análise e desenvolvimento de sistemas"
    }
}

Campos importantes do payload

Campo	Finalidade
`id`	Identificador único do evento. Pode ser utilizado para idempotência.
`event`	Tipo do evento recebido.
`invoice.id`	Identificador da nota fiscal.
`invoice.status`	Status atual da nota fiscal.
`invoice.payment`	Cobrança relacionada à nota fiscal.
`invoice.pdfUrl`	URL do PDF da nota fiscal emitida.
`invoice.xmlUrl`	URL do XML da nota fiscal emitida.
`invoice.number`	Número da nota fiscal.
`invoice.validationCode`	Código de validação da nota fiscal.
`dateCreated`	Data e hora da geração do evento.

📘
Importante
Os campos pdfUrl, xmlUrl, number e validationCode normalmente estarão preenchidos após a autorização da nota fiscal.

Comportamentos importantes

Os Webhooks seguem o modelo de entrega at least once.

Isso significa que um mesmo evento pode ser enviado mais de uma vez.

Por esse motivo, recomenda-se implementar idempotência utilizando o campo:

id

do evento.

Além disso:

eventos podem ser reenviados em caso de falha;
o endpoint deve retornar um código HTTP da família 2xx;
respostas diferentes podem gerar novas tentativas de entrega;
a fila poderá ser interrompida após falhas consecutivas;
eventos permanecem armazenados por até 14 dias;
novos atributos poderão ser adicionados ao payload no futuro.

Segurança

Recomenda-se validar o header:

asaas-access-token

utilizando o token configurado no Webhook.

Também é recomendado permitir chamadas apenas dos IPs oficiais do Asaas.

Boas práticas

Processe os eventos de forma assíncrona.
Responda rapidamente com HTTP 2xx.
Utilize o campo id do evento para implementar idempotência.
Utilize invoice.id como identificador principal da nota fiscal.
Não dependa da ordem de recebimento dos eventos.
Monitore os Logs de Webhooks.
Prepare sua aplicação para receber novos campos no payload.

Erros comuns

INVOICE_ERROR

Indica falha na emissão da nota fiscal.

Recomenda-se consultar os detalhes do erro e verificar a configuração fiscal da conta.

Evento duplicado

Como a entrega é feita no modelo "at least once", um mesmo evento pode ser reenviado.

Utilize o identificador do evento para evitar reprocessamentos.

Endpoint retornando erro

Caso a aplicação retorne respostas fora da família 2xx, novas tentativas poderão ocorrer.

PDF ou XML indisponíveis

Os campos pdfUrl e xmlUrl somente estarão preenchidos após a autorização da nota fiscal.

Impactos operacionais

Os eventos de notas fiscais podem ser utilizados para sincronização com ERPs, CRMs e sistemas fiscais.

Falhas no processamento podem causar:

divergências fiscais entre sistemas;
indisponibilidade do PDF ou XML para clientes;
perda de sincronização com sistemas externos;
duplicidade de processamento;
interrupção da fila de Webhooks.

Por esse motivo, recomenda-se monitorar continuamente a integração.

👍
Retorno do Webhook com tipagem e ENUMs
Caso você queira saber qual o tipo de cada campo e os retornos de ENUMs disponíveis, confira a resposta 200 no endpoint "Recuperar uma nota fiscal" na documentação.

🚧
Atenção

Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.

Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do Webhook.

Conteúdos relacionados

Eventos de Webhooks;
Receba eventos do Asaas no seu endpoint de Webhook;
Como implementar idempotência em Webhooks;
Logs de Webhooks;
Fila pausada;
Penalização de filas;
Notas fiscais.