Eventos para antecipações

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

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

Os eventos que o Asaas notifica são:

RECEIVABLE_ANTICIPATION_CANCELLED - Antecipação cancelada.
RECEIVABLE_ANTICIPATION_SCHEDULED - Antecipação agendada.
RECEIVABLE_ANTICIPATION_PENDING - Antecipação em análise.
RECEIVABLE_ANTICIPATION_CREDITED - Antecipação creditada.
RECEIVABLE_ANTICIPATION_DEBITED - Antecipação debitada.
RECEIVABLE_ANTICIPATION_DENIED - Solicitação da antecipação negada.
RECEIVABLE_ANTICIPATION_OVERDUE - Antecipação vencida.

Comportamentos importantes

Os Webhooks do Asaas utilizam o modelo de entrega at least once, ou seja, um mesmo evento pode ser enviado mais de uma vez.

Por esse motivo, recomenda-se implementar idempotência utilizando o identificador do evento:

id

Além disso:

respostas HTTP fora da família 2xx podem gerar novas tentativas de entrega;
a fila de sincronização poderá ser interrompida após falhas consecutivas;
os eventos permanecem armazenados por até 14 dias;
novos atributos poderão ser adicionados ao payload futuramente.

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

Campo	Descrição
`id`	Identificador único do evento
`event`	Tipo do evento recebido
`anticipation.id`	Identificador da antecipação
`anticipation.status`	Situação atual da antecipação
`anticipation.payment`	Cobrança relacionada
`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.

Boas práticas

Recomendamos:

validar o header asaas-access-token;
responder rapidamente utilizando códigos HTTP da família 2xx;
implementar idempotência utilizando o campo id;
processar os eventos de forma assíncrona;
monitorar continuamente os Logs de Webhooks;
preparar a aplicação para aceitar novos atributos sem gerar exceções.

Erros comuns

Evento processado mais de uma vez

Como a entrega segue o modelo at least once, o mesmo evento poderá ser reenviado.

Utilize o identificador do evento para evitar duplicidades.

Respostas HTTP diferentes de 2xx

Respostas diferentes da família 2xx podem provocar novas tentativas de entrega.

Falhas no processamento

Caso ocorram falhas consecutivas, a fila poderá ser interrompida, impedindo a entrega de novos eventos até a correção do problema.

🚧
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.