Endpoint responsável por atualizar as configurações de uma notificação já criada para um cliente.

As notificações são utilizadas pelo Asaas para avisar você e/ou o pagador sobre eventos relacionados às cobranças, como criação, vencimento, recebimento, atraso ou atualização de dados da cobrança. Cada cliente possui um conjunto próprio de notificações, criado automaticamente pelo Asaas no momento do cadastro.

Use este endpoint quando sua integração precisar alterar uma notificação específica de um cliente, modificando seus canais de envio, ativando ou desativando a notificação, ou ajustando o momento em que ela será enviada.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• desabilitar uma notificação específica de um cliente;
• ativar ou desativar canais de envio, como e-mail, SMS, WhatsApp ou ligação;
• configurar se a notificação será enviada ao pagador, ao provedor ou a ambos;
• alterar o prazo de envio de notificações antes ou após o vencimento;
• padronizar o comportamento de comunicação de clientes criados pela sua plataforma;
• ajustar notificações de um cliente sem alterar todas as demais notificações dele.

Esse endpoint é indicado para alterações individuais. Caso seja necessário atualizar várias notificações de um mesmo cliente de uma só vez, utilize o endpoint Atualizar notificações em lote.

Fluxo recomendado

Antes de atualizar uma notificação, a integração deve recuperar as notificações existentes do cliente para identificar qual delas precisa ser alterada.

Criar ou identificar o cliente
↓
Recuperar notificações do cliente
↓
Localizar a notificação desejada
↓
Armazenar ou utilizar o id da notificação
↓
Atualizar a notificação existente
↓
Validar os canais e o momento de envio configurados

Para recuperar as notificações de um cliente, utilize:

GET /v3/customers/{id}/notifications

Depois de identificar a notificação desejada na lista retornada, utilize o campo id da notificação para realizar a atualização.

Atualização da notificação

PUT /v3/notifications/{id}

O parâmetro id representa o identificador único da notificação que será atualizada.

Esse identificador não é o ID do cliente nem o ID da cobrança. Ele é retornado na listagem de notificações do cliente e identifica uma configuração específica de notificação.

Parâmetros que alteram o comportamento da notificação

Embora a referência técnica liste todos os campos disponíveis, alguns parâmetros têm impacto direto no comportamento da comunicação enviada.

Diferença entre desativar a notificação e desativar canais

O campo enabled controla a notificação como um todo.

Quando enabled é definido como false, a notificação deixa de ser enviada, mesmo que algum canal esteja marcado como ativo.

Já os campos de canal, como emailEnabledForCustomer, smsEnabledForCustomer e whatsappEnabledForCustomer, controlam apenas por onde a notificação será enviada.

Exemplo:

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": false,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

Neste exemplo, a notificação continua ativa, mas será enviada apenas por e-mail para o pagador.

Uso do scheduleOffset

O campo scheduleOffset define em quantos dias a notificação será enviada em relação ao vencimento da cobrança.

Esse campo deve ser utilizado principalmente em notificações relacionadas a aviso de vencimento e cobrança vencida.

Para o evento PAYMENT_DUEDATE_WARNING, os valores aceitos são:

0, 5, 10, 15, 30

Para o evento PAYMENT_OVERDUE, os valores aceitos são:

1, 7, 15, 30

Exemplo de atualização

O exemplo abaixo mantém a notificação ativa e envia a comunicação apenas por e-mail para o pagador.

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": false,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

Esse tipo de configuração pode ser utilizado quando a plataforma deseja evitar múltiplos canais de cobrança para o pagador, mantendo apenas o envio por e-mail.

Notificações por WhatsApp e ligação

As notificações para o pagador podem ser enviadas por WhatsApp ou ligação automática, desde que os dados cadastrais do cliente permitam esse envio.

Para ativar notificações por ligação, o cliente deve possuir telefone fixo ou móvel cadastrado.

{
  "enabled": true,
  "phoneCallEnabledForCustomer": true
}

Para ativar notificações por WhatsApp:

{
  "enabled": true,
  "whatsappEnabledForCustomer": true
}

Cenários comuns de uso

Enviar notificações apenas para o pagador

Use essa configuração quando a plataforma não quiser receber cópias das notificações enviadas ao cliente final.

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": true,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

Desabilitar uma notificação específica

Use essa configuração quando determinado tipo de comunicação não deve ser enviado.

{
  "enabled": false
}

Enviar aviso antes do vencimento

Use essa configuração em notificações do tipo PAYMENT_DUEDATE_WARNING.

{
  "enabled": true,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": true,
  "scheduleOffset": 10
}

Neste exemplo, a notificação será enviada 10 dias antes do vencimento, desde que o evento da notificação seja compatível com esse tipo de agendamento.

Cuidados importantes

• Recupere as notificações do cliente antes de tentar atualizá-las.
• Utilize sempre o id da notificação, não o id do cliente ou da cobrança.
• Valide o evento da notificação antes de alterar o scheduleOffset.
• Evite ativar muitos canais ao mesmo tempo sem necessidade, pois isso pode gerar comunicações excessivas ao pagador.
• Considere possíveis custos de envio antes de habilitar SMS, WhatsApp ou ligação.
• Para alterações em várias notificações, prefira o endpoint de atualização em lote.
• Para impedir todas as notificações de um cliente no momento da criação, utilize o atributo notificationDisabled no cadastro do cliente.

Erros comuns

Usar o ID do cliente no lugar do ID da notificação

O endpoint espera o identificador da notificação no path.

PUT /v3/notifications/{id}

O valor informado em {id} deve ter sido retornado pela listagem de notificações do cliente.

Alterar o scheduleOffset com valor incompatível

Cada evento aceita valores específicos de scheduleOffset. Caso seja enviado um valor inválido para o tipo de notificação, a API retornará erro de validação.

Desativar canais sem desativar a notificação

Se enabled continuar como true, a notificação continuará ativa. Caso todos os canais desejados estejam desativados, valide se a intenção é realmente manter a notificação ativa ou se ela deve ser desabilitada por completo.

Conteúdos relacionados

• Introdução às notificações
• Notificações padrões
• Recuperar notificações de um cliente
• Atualizar notificações em lote
• Criar novo cliente
• Desabilitar notificações ao criar cliente