Eventos para notas fiscais

Use os eventos de nota fiscal para acompanhar emissão, atualização, autorização, cancelamento e falhas das notas fiscais emitidas pelo Asaas.

Cada notificação contém o tipo do evento em event e os dados da nota fiscal no objeto invoice.

Eventos disponíveis

Fluxo de emissão

O fluxo comum de emissão passa pela criação, sincronização com a prefeitura e autorização da nota fiscal.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["INVOICE_CREATED"] --> B["Enviar para a prefeitura"]
    B --> C["INVOICE_SYNCHRONIZED"]
    C --> D["Processar autorização"]
    D --> E["INVOICE_AUTHORIZED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D validacao
    class E sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

O evento INVOICE_UPDATED pode ocorrer quando os dados da nota fiscal forem alterados.

Fluxo de cancelamento

Quando o cancelamento é solicitado, acompanhe o resultado pelo evento enviado após o processamento.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Solicitar cancelamento"] --> B["INVOICE_PROCESSING_<br/>CANCELLATION"]
    B --> C{"Cancelamento autorizado?"}

    C --> CSim(("Sim"))
    C --> CNao(("Não"))

    CSim --> D["INVOICE_CANCELED"]
    CNao --> E["INVOICE_CANCELLATION_<br/>DENIED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B validacao
    class C decisao
    class D sucesso

    class CSim respostaSim
    class CNao,E respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#EF4444,stroke-width:4px

Se ocorrer uma falha relacionada à nota fiscal, será enviado INVOICE_ERROR.

Payload do evento

A notificação é enviada via POST com o evento e os dados da nota fiscal.

{
    "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

Como tratar os eventos

Ao receber um evento de nota fiscal:

1. identifique a alteração pelo campo event;
2. persista o id para impedir processamento duplicado;
3. utilize invoice.id para identificar a nota fiscal;
4. responda HTTP 200 após confirmar a persistência;
5. processe a atualização no seu sistema.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez.

Consulte como implementar idempotência em Webhooks.

Como tratar eventos específicos

INVOICE_AUTHORIZED

Quando a nota for autorizada, utilize os dados do objeto invoice para atualizar seu sistema e, quando disponíveis, armazenar ou disponibilizar pdfUrl, xmlUrl, number e validationCode.

INVOICE_ERROR

O evento indica uma falha relacionada à nota fiscal.

Verifique os dados retornados no evento e a configuração fiscal utilizada na emissão antes de realizar uma nova tentativa ou intervenção.

INVOICE_CANCELLATION_DENIED

O cancelamento não foi autorizado. Mantenha a nota fiscal sincronizada com o estado retornado pelo Asaas e trate a recusa conforme a regra da sua integração.

Valide a origem do Webhook

Quando utilizar authToken, valide o header:

asaas-access-token

Se sua infraestrutura restringir requisições por origem, consulte os IPs oficiais do Asaas.

Próximos passos

• Receba eventos do Asaas no seu endpoint de Webhook
• Implemente idempotência em Webhooks
• Monitore os Logs de Webhooks
• Consulte os demais Eventos de Webhooks
• Conheça o fluxo de Notas Fiscais