Endpoint responsável por atualizar, em uma única requisição, as configurações de várias notificações já existentes de um cliente.

As notificações definem como e quando o Asaas irá comunicar eventos relacionados às cobranças, como criação, vencimento, recebimento ou atraso. Essas configurações podem determinar os canais utilizados, como e-mail, SMS, voz ou WhatsApp, e quem receberá a comunicação, como o cliente pagador ou o fornecedor.

Este endpoint deve ser utilizado quando sua integração precisa padronizar ou ajustar múltiplas notificações de um mesmo cliente sem realizar uma chamada individual para cada notificação.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• configurar notificações padrão após a criação de um cliente;
• ativar ou desativar vários tipos de notificação de uma só vez;
• alterar os canais de comunicação utilizados para diferentes eventos;
• definir se determinadas notificações serão enviadas ao cliente, ao fornecedor ou a ambos;
• aplicar uma política única de comunicação para clientes cadastrados pela sua plataforma;
• reduzir a quantidade de chamadas à API ao configurar notificações em lote.

Esse recurso é especialmente útil em fluxos automatizados de onboarding, nos quais a aplicação cria um cliente e, em seguida, ajusta as notificações conforme a regra de negócio da plataforma.

Fluxo recomendado

Em uma integração típica, a atualização de notificações em lote segue o fluxo abaixo:

Criar ou identificar o cliente
↓
Recuperar as notificações existentes do cliente
↓
Selecionar quais notificações precisam ser alteradas
↓
Montar o payload com o customer e a lista de notifications
↓
Enviar a atualização em lote
↓
Validar a resposta da API
↓
Persistir ou registrar a configuração aplicada, se necessário

As notificações precisam existir antes da atualização. Por isso, antes de chamar este endpoint, consulte as notificações do cliente e utilize os identificadores retornados pela API.

Parâmetros principais da requisição

Este endpoint utiliza dois parâmetros principais no corpo da requisição:

O campo customer deve receber o identificador do cliente exatamente como retornado pela API do Asaas, normalmente no formato cus_....

O campo notifications deve conter as notificações que serão alteradas. Cada item da lista deve representar uma notificação existente e deve estar relacionado ao cliente informado no campo customer.

Dependências obrigatórias

Antes de utilizar este endpoint, sua integração deve garantir que:

• o cliente já exista no Asaas;
• o identificador do cliente tenha sido armazenado pela aplicação;
• as notificações do cliente já tenham sido recuperadas;
• os identificadores das notificações a serem alteradas sejam válidos;
• as notificações enviadas pertençam ao cliente informado;
• a requisição esteja autenticada com uma chave de API válida.

Este endpoint não cria novas notificações. Ele apenas atualiza notificações já existentes.

Exemplo de uso

Um cenário comum é padronizar as notificações logo após a criação de um novo cliente.

{
  "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": true,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": true,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": false,
      "smsEnabledForProvider": false
    }
  ]
}

Funcionamento da atualização em lote

Ao receber a requisição, o Asaas utiliza o campo customer para identificar o cliente e aplica as alterações nas notificações enviadas na lista notifications.

Cada item da lista representa uma notificação que deve ser atualizada. As configurações enviadas determinam como aquela notificação ficará configurada após o processamento.

Notificações que não forem enviadas na lista não devem ser consideradas parte da atualização solicitada. Caso sua integração precise manter um padrão completo de comunicação, envie no lote todas as notificações que precisam ser controladas pela sua regra de negócio.

Regras de negócio importantes

Ao utilizar este endpoint, considere as seguintes regras:

• o cliente informado em customer deve existir;
• cada notificação enviada deve existir previamente;
• as notificações enviadas devem pertencer ao cliente informado;
• a atualização é feita sobre configurações de notificações já existentes;
• o endpoint não deve ser utilizado para criar novas notificações;
• os canais habilitados dependem dos dados disponíveis no cadastro do cliente e das permissões da conta;
• notificações por voz exigem que o cliente possua telefone cadastrado;
• configurações de notificação podem impactar diretamente a comunicação enviada ao pagador;
• notificações de cobrança podem gerar custos conforme as taxas aplicáveis à conta.

Comportamentos relevantes

Alguns comportamentos devem ser considerados durante a implementação:

• alterações nas notificações passam a afetar as próximas comunicações geradas para o cliente;
• cobranças ou comunicações já enviadas anteriormente não são recriadas ou reenviadas automaticamente;
• se uma notificação for desativada, novas comunicações daquele tipo deixarão de ser enviadas conforme a configuração aplicada;
• se um canal for desativado para o cliente, aquele canal deixará de ser utilizado para a respectiva notificação;
• se um canal for ativado, valide se o cliente possui os dados necessários para receber a comunicação, como e-mail ou telefone;
• alterações feitas em lote devem ser validadas pela resposta da API antes de serem consideradas concluídas pela integração.

Cuidados com atualizações em lote

Por se tratar de uma atualização em lote, recomenda-se que a aplicação trate o envio como uma operação sensível.

Antes de enviar a requisição:

• evite enviar notificações duplicadas no mesmo lote;
• valide se todos os IDs de notificação pertencem ao cliente informado;
• monte o payload a partir da consulta mais recente das notificações do cliente;
• envie apenas alterações intencionais;
• registre internamente qual padrão de notificação foi aplicado;
• evite alterar notificações durante fluxos críticos sem validar o impacto para o cliente final.

Caso ocorra erro na requisição, não considere a configuração aplicada sem antes consultar novamente as notificações do cliente ou repetir a atualização de forma controlada.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Sempre valide a resposta da API e, em caso de dúvida, consulte novamente as notificações do cliente para confirmar o estado final da configuração.

Cuidados em Sandbox

A atualização de notificações em lote pode ser testada em Sandbox.

No entanto, nem todos os canais possuem o mesmo comportamento do ambiente de Produção. Em especial, notificações por WhatsApp podem não estar disponíveis ou não ser totalmente suportadas em Sandbox.

Também é importante evitar o uso de dados reais de terceiros durante testes, pois canais como e-mail e SMS podem disparar comunicações reais dependendo do cenário testado.

Boas práticas

Para uma integração mais segura e previsível, recomenda-se:

• recuperar as notificações do cliente antes de atualizá-las;
• armazenar o ID do cliente retornado pelo Asaas;
• aplicar padrões de notificação logo após a criação do cliente;
• validar o payload antes do envio;
• manter logs das configurações aplicadas;
• evitar dados reais em testes de Sandbox;
• tratar respostas de erro antes de seguir com a criação de cobranças;
• revisar periodicamente as configurações de notificação utilizadas pela integração.

Impacto operacional

As configurações de notificação afetam diretamente a comunicação com o cliente final.

Uma configuração incorreta pode causar:

• ausência de avisos de cobrança;
• envio de comunicações para canais indesejados;
• cobrança por notificações não planejadas;
• falhas de comunicação com clientes sem e-mail ou telefone cadastrados;
• divergência entre a régua de comunicação esperada pela plataforma e a executada pelo Asaas.

Por isso, a atualização em lote deve ser usada com atenção em fluxos automatizados e, sempre que possível, validada antes da criação de cobranças em produção.

Conteúdos relacionados

Consulte também:

• Alterando notificações de um cliente;
• Recuperar notificações de um cliente;
• Atualizar notificação existente;
• Criar novo cliente;
• Notificações padrões;
• O que pode ser testado em Sandbox;
• Cobranças.