Eventos para antecipações

Escute os eventos do Asaas para ter sua integração em dia.

Use os eventos de antecipação para acompanhar automaticamente as mudanças de estado de uma antecipação de recebíveis.

Cada notificação informa o evento ocorrido em event e os dados atuais da operação no objeto anticipation.

Eventos disponíveis

Evento	Quando ocorre
`RECEIVABLE_ANTICIPATION_CANCELLED`	A antecipação é cancelada.
`RECEIVABLE_ANTICIPATION_SCHEDULED`	A antecipação é agendada.
`RECEIVABLE_ANTICIPATION_PENDING`	A antecipação está em análise.
`RECEIVABLE_ANTICIPATION_CREDITED`	A antecipação é creditada.
`RECEIVABLE_ANTICIPATION_DEBITED`	A antecipação é debitada.
`RECEIVABLE_ANTICIPATION_DENIED`	A solicitação de antecipação é negada.
`RECEIVABLE_ANTICIPATION_OVERDUE`	A antecipação fica vencida.

Os eventos representam mudanças no processamento da antecipação. Não assuma que todas as operações passarão por todos os eventos acima ou que eles formam uma sequência obrigatória.

Como interpretar os eventos

Evento	Tratamento na integração
`RECEIVABLE_ANTICIPATION_SCHEDULED`	Mantenha a operação como agendada.
`RECEIVABLE_ANTICIPATION_PENDING`	Indique que a antecipação está em análise.
`RECEIVABLE_ANTICIPATION_CREDITED`	Confirme o crédito da antecipação no seu sistema.
`RECEIVABLE_ANTICIPATION_DEBITED`	Atualize a operação para refletir o débito.
`RECEIVABLE_ANTICIPATION_DENIED`	Marque a solicitação como negada e consulte `anticipation.denialObservation`, quando preenchido.
`RECEIVABLE_ANTICIPATION_CANCELLED`	Atualize a operação como cancelada.
`RECEIVABLE_ANTICIPATION_OVERDUE`	Atualize a operação para refletir o vencimento.

event identifica a alteração notificada pelo Webhook. anticipation.status representa a situação atual da antecipação no payload.

Payload do evento

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

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
  "event": "RECEIVABLE_ANTICIPATION_CREDITED",
  "dateCreated": "2024-06-12 16:45:03",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "anticipation": {
    "object": "anticipation",
    "id": "29ad50e9-64ee-427e-a00c-a3999510ca0a",
    "installment": null,
    "payment": "pay_4310966350068380",
    "status": "CREDITED",
    "anticipationDate": "2022-09-19",
    "dueDate": "2022-09-30",
    "requestDate": "2022-09-19",
    "fee": 5.64,
    "anticipationDays": 11,
    "netValue": 302.37,
    "totalValue": 310,
    "value": 308.01,
    "denialObservation": null
  }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica o evento recebido.
`anticipation.id`	Identificador da antecipação.
`anticipation.status`	Situação atual da antecipação.
`anticipation.payment`	Cobrança relacionada à antecipação, quando aplicável.
`anticipation.installment`	Parcelamento relacionado à antecipação, quando aplicável.
`anticipation.netValue`	Valor líquido creditado.
`anticipation.totalValue`	Valor bruto da antecipação.
`anticipation.fee`	Taxa aplicada.
`anticipation.denialObservation`	Motivo da recusa, quando existir.

👍
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 única antecipação" na documentação.

Como tratar os eventos

Ao receber um evento de antecipação:

identifique a alteração pelo campo event;
persista o id para impedir processamento duplicado;
utilize anticipation.id para localizar a antecipação no seu sistema;
atualize a operação conforme o evento e anticipation.status;
responda HTTP 200 após confirmar a persistência;
processe regras adicionais de forma assíncrona.

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.

Para acompanhar as mudanças de estado da antecipação, prefira esses eventos em vez de consultar periodicamente a API. Use a consulta individual apenas quando precisar recuperar pontualmente o estado atual de uma operaçã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.

Próximos passos

Updated 14 days ago

Did this page help you?