Eventos para recargas de celular

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

Os eventos que o Asaas notifica são:

• MOBILE_PHONE_RECHARGE_PENDING - Recarga de celular pendente.
• MOBILE_PHONE_RECHARGE_CANCELLED - Recarga de celular cancelada.
• MOBILE_PHONE_RECHARGE_CONFIRMED - Recarga de celular confirmada.
• MOBILE_PHONE_RECHARGE_REFUNDED - Recarga de celular estornada.

Quando utilizar

Os Webhooks de recarga de celular são recomendados quando sua aplicação precisa acompanhar automaticamente o processamento das recargas realizadas através do Asaas.

Alguns exemplos:

• atualização de sistemas internos;
• acompanhamento do status das recargas;
• auditoria financeira;
• sincronização com ERPs;
• notificações aos usuários.

Comportamentos importantes

Os Webhooks do Asaas utilizam o modelo de entrega at least once, portanto um mesmo evento poderá 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 provocar novas tentativas de envio;
• a fila poderá ser interrompida após falhas consecutivas;
• os eventos permanecem armazenados por até 14 dias;
• novos atributos poderão ser adicionados futuramente.

Fluxo comum dos eventos

Normalmente o fluxo ocorre da seguinte maneira:

MOBILE_PHONE_RECHARGE_PENDING
↓
MOBILE_PHONE_RECHARGE_CONFIRMED

Em situações específicas também podem ocorrer:

MOBILE_PHONE_RECHARGE_PENDING
↓
MOBILE_PHONE_RECHARGE_CANCELLED

ou

MOBILE_PHONE_RECHARGE_CONFIRMED
↓
MOBILE_PHONE_RECHARGE_REFUNDED

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": "MOBILE_PHONE_RECHARGE_CONFIRMED",
   "dateCreated": "2024-06-12 16:45:03",
   "account": {
      "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
      "ownerId": null
   },
   "mobilePhoneRecharge": {
      "id": "29ad50e9-64ee-427e-a00c-a3999510ca0a",
      "value": 15,
      "phoneNumber": "62982055478",
      "status": "CONFIRMED",
      "canBeCancelled": false,
      "operatorName": "Tim"
   }
}

Campos importantes

👍

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 recarga de celular" 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 duplicado

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

Utilize o identificador do evento para evitar processamentos duplicados.

HTTP diferente de 2xx

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

Novos campos no payload

Sua aplicação deve ignorar campos desconhecidos para manter compatibilidade com futuras versões.

Impactos operacionais

Falhas no processamento dos Webhooks podem provocar:

• novas tentativas de entrega;
• interrupção da fila de sincronização;
• inconsistências entre sistemas;
• atraso na atualização do status das recargas;
• perda permanente dos eventos após 14 dias.

🚧

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.