Altere as notificações de um cliente

Consulte as notificações criadas para o cliente e altere apenas as configurações que sua integração precisa controlar.

Você pode ativar ou desativar uma notificação, escolher os canais de envio e, em eventos compatíveis, alterar o momento do disparo.

Antes de começar

Tenha o ID do cliente no formato cus_....

As notificações são criadas automaticamente pelo Asaas no cadastro do cliente. Para conhecer a configuração inicial, consulte Notificações padrões.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Recuperar as notificações"] --> B["Identificar os IDs"]
    B --> C{"Quantas serão alteradas?"}

    C --> CUma(("Uma"))
    C --> CVarias(("Várias"))

    CUma --> D["Atualizar a notificação"]
    CVarias --> E["Atualizar em lote"]

    D --> F["Validar a configuração"]
    E --> F

    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 respostaOpcao fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class CUma respostaSim
    class CVarias respostaOpcao

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

1. Recupere as notificações do cliente

Utilize:

GET /v3/customers/{id}/notifications

Consulte o endpoint Recuperar notificações de um cliente.

A resposta retorna as notificações existentes e o id de cada configuração:

{
  "object": "list",
  "data": [
    {
      "id": "not_000042762597",
      "customer": "cus_000005358829",
      "enabled": true,
      "emailEnabledForProvider": true,
      "smsEnabledForProvider": false,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": true,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "event": "PAYMENT_RECEIVED",
      "scheduleOffset": 0
    }
  ]
}

Utilize o id da notificação, e não o ID do cliente ou da cobrança, nas etapas seguintes.

Um cliente pode possuir mais de uma notificação para o mesmo event. Nesses casos, utilize também scheduleOffset para identificar a configuração desejada.

2. Atualize uma notificação

Para alterar apenas uma configuração:

PUT /v3/notifications/{id}

Exemplo para manter a notificação ativa e enviar somente e-mail ao cliente:

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

Consulte o endpoint Atualizar notificação existente.

Os principais campos de configuração são:

Se enabled for false, a notificação não será enviada, mesmo que algum canal permaneça habilitado.

3. Altere o momento do envio

scheduleOffset é utilizado nas notificações relacionadas ao vencimento.

Ao atualizar uma notificação, utilize os valores compatíveis com o evento:

Em PAYMENT_DUEDATE_WARNING, o valor representa dias antes do vencimento ou o próprio dia quando 0.

Em PAYMENT_OVERDUE, representa dias após o vencimento.

Exemplo de aviso 10 dias antes:

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

4. Atualize várias notificações em uma chamada

Quando precisar alterar várias configurações do mesmo cliente, utilize:

PUT /v3/notifications/batch

Informe o cliente e somente as notificações que precisam ser alteradas:

{
  "customer": "cus_000005401844",
  "notifications": [
    {
      "id": "not_000000000001",
      "enabled": true,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": false,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": true,
      "smsEnabledForProvider": false
    },
    {
      "id": "not_000000000002",
      "enabled": false,
      "emailEnabledForCustomer": false,
      "smsEnabledForCustomer": false,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": false,
      "smsEnabledForProvider": false
    }
  ]
}

Cada id precisa representar uma notificação existente e pertencer ao cliente informado em customer.

Notificações que não forem enviadas em notifications não fazem parte da atualização solicitada.

Consulte o endpoint Atualizar notificações existentes em lote.

Valide a configuração

Após a atualização, consulte novamente:

GET /v3/customers/{id}/notifications

Confirme se enabled, os canais e scheduleOffset correspondem à configuração esperada.

Alterações afetam as próximas comunicações. Notificações já enviadas não são recriadas ou reenviadas automaticamente.

Próximos passos

• Consulte as Notificações padrões
• Recupere as notificações de um cliente
• Atualize uma notificação existente
• Atualize notificações em lote
• Volte para a Introdução de Notificações