Endpoint responsável por atualizar as informações cadastrais de um cliente já existente no Asaas utilizando seu identificador único (id).

A atualização é utilizada para manter os dados sincronizados entre o sistema de origem e o Asaas, garantindo que futuras cobranças, notificações e consultas utilizem as informações mais recentes do cliente.

Quando utilizar

Utilize este endpoint sempre que sua integração precisar atualizar dados cadastrais de um cliente já criado no Asaas.

Alguns cenários comuns incluem:

• alteração de nome, e-mail, telefone ou celular;
• atualização de endereço;
• alteração de CPF ou CNPJ cadastrado;
• inclusão de e-mails adicionais para notificações;
• alteração do identificador do cliente no sistema de origem;
• atualização da configuração de envio de notificações de cobrança;
• sincronização de dados entre ERP, CRM, e-commerce ou plataforma própria e o Asaas.

Antes da atualização, é necessário conhecer o identificador (id) do cliente no Asaas, normalmente obtido durante sua criação ou por meio da consulta de clientes.

Quando não utilizar

Não utilize este endpoint para:

• criar um novo cliente;
• remover um cliente;
• restaurar um cliente removido;
• alterar cobranças já criadas;
• alterar assinaturas já criadas;
• alterar dados financeiros de pagamentos já emitidos;
• atualizar notificações específicas do cliente em lote;
• substituir o fluxo de criação de clientes.

Caso o cliente ainda não exista no Asaas, utilize o endpoint de criação de cliente.

Caso precise alterar notificações específicas de cobrança, utilize os endpoints de notificações do cliente.

Funcionamento da atualização

A atualização modifica apenas o cadastro do cliente informado pelo identificador enviado na requisição.

Este endpoint não cria novos clientes nem altera cobranças, assinaturas, notas fiscais ou demais recursos já existentes. Entretanto, as informações atualizadas poderão ser utilizadas pelas operações realizadas após a alteração cadastral.

A atualização deve ser tratada como uma alteração cadastral do cliente existente, mantendo o mesmo id.

Campos ausentes, vazios ou nulos

Ao montar a requisição de atualização, tenha atenção ao tratamento dos campos:

Parâmetro da requisição

Este endpoint utiliza o identificador do cliente no path da requisição.

O id deve corresponder a um cliente existente na conta Asaas autenticada.

Exemplo de identificador:

cus_000005401844

Esse identificador é retornado no momento da criação do cliente e também pode ser obtido por meio da listagem ou consulta de clientes.

Parâmetros do body

Os campos do body devem ser enviados conforme os dados cadastrais que precisam ser atualizados.

Parâmetros que merecem atenção

Embora todos os parâmetros estejam documentados na referência técnica, alguns campos costumam ter maior impacto durante a integração:

• id — identifica qual cliente será atualizado.
• cpfCnpj — deve representar corretamente o documento do cliente.
• email — pode ser utilizado em comunicações e notificações.
• phone e mobilePhone — podem ser utilizados em comunicações e validações.
• postalCode, address, addressNumber e province — impactam o cadastro de endereço do cliente.
• externalReference — facilita a sincronização entre o Asaas e o sistema de origem.
• notificationDisabled — define se o cliente continuará recebendo notificações de cobrança.
• additionalEmails — adiciona destinatários extras para as notificações de cobrança.
• foreignCustomer — deve ser informado para clientes estrangeiros quando aplicável.

Permissão e autenticação

Para utilizar este endpoint, a requisição deve ser autenticada com uma API Key válida da conta Asaas.

A chave utilizada deve pertencer ao mesmo ambiente da requisição:

• API Key de Sandbox para chamadas em Sandbox;
• API Key de Produção para chamadas em Produção.

Caso a API Key esteja ausente, inválida ou pertença a outro ambiente, a requisição poderá retornar erro de autorização.

Exemplo de chamada

curl --request PUT \
  --url https://api-sandbox.asaas.com/v3/customers/cus_000005401844 \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "90999999999",
    "mobilePhone": "90999999999",
    "address": "Av. Paulista",
    "addressNumber": "150",
    "complement": "Sala 201",
    "province": "Centro",
    "postalCode": "01310000",
    "externalReference": "12987382",
    "notificationDisabled": false,
    "additionalEmails": "[email protected],[email protected]",
    "observations": "ótimo pagador, nenhum problema até o momento",
    "foreignCustomer": false
  }'

Exemplo de resposta

Em caso de sucesso, a API retorna os dados atualizados do cliente.

{
  "object": "customer",
  "id": "cus_000005401844",
  "dateCreated": "2024-07-12",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "90999999999",
  "mobilePhone": "90999999999",
  "address": "Av. Paulista",
  "addressNumber": "150",
  "complement": "Sala 201",
  "province": "Centro",
  "city": 12565,
  "cityName": "São Paulo",
  "state": "SP",
  "country": "Brasil",
  "postalCode": "01310000",
  "cpfCnpj": "24971563792",
  "personType": "FISICA",
  "deleted": false,
  "additionalEmails": "[email protected],[email protected]",
  "externalReference": "12987382",
  "notificationDisabled": false,
  "observations": "ótimo pagador, nenhum problema até o momento",
  "foreignCustomer": false
}

Principais campos da resposta

Exemplo de utilização

Um cenário comum ocorre quando um cliente altera seus dados cadastrais em um ERP, CRM, e-commerce ou plataforma própria.

Após a atualização dessas informações no sistema de origem, a aplicação pode utilizar este endpoint para manter o cadastro sincronizado também no Asaas, evitando divergências entre os sistemas.

Exemplo de fluxo:

Cliente atualiza o cadastro no sistema de origem
↓
Sistema identifica a alteração
↓
Sistema recupera o id do cliente no Asaas
↓
Sistema envia os campos alterados para o Asaas
↓
Asaas atualiza o cadastro do cliente
↓
Sistema registra a sincronização como concluída

Cuidados durante a sincronização

A atualização deve sempre utilizar o identificador correto do cliente.

Também é recomendável definir uma única fonte de verdade para os dados cadastrais, como ERP, CRM ou outro sistema principal, reduzindo o risco de sobrescritas indevidas entre integrações.

Comportamentos importantes

Após uma atualização realizada com sucesso:

• as novas informações passam a compor o cadastro do cliente;
• futuras cobranças e notificações poderão utilizar os dados atualizados;
• o identificador (id) do cliente permanece o mesmo;
• o cliente não é recriado;
• cobranças já existentes não são alteradas automaticamente;
• assinaturas já existentes não são alteradas automaticamente;
• recursos vinculados ao cliente continuam associados ao mesmo id.

Caso o cliente informado não exista ou o identificador seja inválido, a atualização não será realizada.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• o cliente deve existir no Asaas;
• o id informado deve pertencer à conta autenticada;
• a requisição deve ser autenticada com uma API Key válida;
• ao menos um dado cadastral deve ser enviado para atualização;
• dados enviados devem respeitar os formatos esperados;
• additionalEmails deve utilizar e-mails separados por vírgula;
• notificationDisabled deve ser enviado como booleano;
• foreignCustomer deve ser enviado como booleano;
• campos enviados com valores incorretos podem gerar erro de validação;
• a atualização não cria um novo cliente;
• a atualização não remove o cliente;
• a atualização não altera automaticamente cobranças, assinaturas ou demais recursos já emitidos.

Tratamento de erros

Antes de enviar uma atualização, recomenda-se validar internamente se o cliente já foi sincronizado com o Asaas.

Alguns erros comuns durante a integração incluem:

Sempre que possível, trate esses cenários na aplicação para evitar inconsistências entre os sistemas.

Impacto operacional

Como este endpoint altera diretamente o cadastro do cliente, recomenda-se utilizá-lo apenas quando houver mudanças efetivas nas informações cadastrais.

Atualizações desnecessárias podem:

• aumentar o volume de sincronizações;
• dificultar a auditoria de alterações;
• sobrescrever dados atualizados por outro sistema;
• gerar divergências entre ERP, CRM, e-commerce e Asaas;
• impactar notificações futuras enviadas ao cliente;
• afetar futuras cobranças criadas após a atualização.

Por isso, mantenha controle sobre a origem da alteração e registre quando a sincronização foi realizada.

Boas práticas

Para uma implementação mais segura, recomenda-se:

• armazenar o id retornado na criação do cliente;
• utilizar externalReference para relacionar o cliente ao sistema de origem;
• consultar o cliente antes da atualização quando houver dúvida sobre os dados atuais;
• enviar apenas os campos que precisam ser alterados;
• evitar o envio de campos vazios ou nulos sem validação prévia;
• validar CPF, CNPJ, e-mail, telefone e CEP antes de enviar a atualização;
• manter uma única fonte de verdade para os dados cadastrais;
• registrar logs internos da atualização;
• tratar erros 400, 401 e 404;
• testar o fluxo em Sandbox antes de operar em Produção.

Cuidados em Sandbox

Este endpoint pode ser testado em Sandbox.

Durante os testes, recomenda-se validar:

• atualização de dados básicos, como nome, e-mail e telefone;
• atualização de endereço;
• atualização de externalReference;
• envio de additionalEmails;
• alteração de notificationDisabled;
• envio de campos vazios ou nulos, se esse cenário existir na sua integração;
• tentativa de atualização com id inexistente;
• tentativa de atualização com API Key de ambiente incorreto.

Esses testes ajudam a evitar sobrescritas indevidas e falhas de sincronização em Produção.

Conteúdos relacionados

Este endpoint normalmente faz parte do fluxo abaixo:

Criar cliente
        ↓
Armazenar o id retornado
        ↓
Consultar cliente, quando necessário
        ↓
Atualizar cliente
        ↓
Criar cobranças, assinaturas ou demais operações

Caso sua integração ainda não possua o identificador do cliente, consulte também:

• Criar cliente;
• Listar clientes;
• Recuperar cliente por ID;
• Remover cliente;
• Restaurar cliente removido;
• Recuperar notificações de um cliente;
• Atualizar notificações do cliente.