Guia de Clientes

Confira o guia de clientes para mais informações.

Endpoint responsável por cadastrar um novo cliente na conta Asaas.

Esse cadastro representa a base para operações posteriores da integração, como criação de cobranças, assinaturas e demais fluxos que exigem um pagador previamente identificado.

Após a criação, a API retorna o identificador único do cliente no Asaas, que deve ser armazenado pela aplicação para utilização nas próximas chamadas.

Parâmetros principais da requisição

Alguns campos possuem papel importante no comportamento da integração:

• name — Nome do cliente exibido no cadastro
• cpfCnpj — Documento do cliente (critério comum de validação de duplicidade)
• mobilePhone e email — Dados utilizados para comunicação e notificações
• externalReference — Identificador do cliente no sistema de origem (altamente recomendado)
• notificationDisabled — Define se o cliente receberá notificações
• additionalEmails — Destinatários adicionais para notificações
• groupName — Permite agrupamento lógico de clientes
• foreignCustomer — Deve ser true para clientes estrangeiros

Identificador retornado na criação

A resposta da API retorna o identificador único do cliente no Asaas.

Esse identificador deve ser armazenado pela aplicação, pois será utilizado em operações como:

• criação de cobranças
• criação de assinaturas
• atualização cadastral
• consulta individual
• recuperação de notificações

Embora o documento possa ser utilizado em buscas, o identificador do Asaas é o dado mais confiável para relacionamento entre entidades dentro da API.

Funcionamento da criação do cliente

Este endpoint é responsável por registrar o pagador que será utilizado em operações posteriores da integração.

Após a criação, a API retorna o identificador único do cliente no Asaas, que deve ser armazenado pela aplicação para uso nas próximas chamadas.

Como a API permite a criação de clientes duplicados, integrações que exigem unicidade cadastral devem implementar validação prévia, normalmente com base em cpfCnpj, externalReference ou reaproveitamento do identificador já persistido internamente.

🚧

Atenção

A API permite a criação de clientes duplicados.
É responsabilidade da integração implementar estratégias de prevenção de duplicidade antes da criação.

Estratégia de prevenção de duplicidade

As estratégias mais comuns são:

• buscar previamente por cpfCnpj
• validar por externalReference
• armazenar internamente o ID do cliente já criado e reutilizá-lo

Essa validação é especialmente importante em cenários com:

• reprocessamento de eventos
• filas assíncronas
• tentativas automáticas de cadastro

Uso recomendado do externalReference

Sempre que possível, é recomendável enviar o campo externalReference.

Esse atributo facilita a conciliação entre sistemas, reduz a dependência de buscas por nome ou documento e ajuda a evitar criação duplicada.

Em integrações mais robustas, esse campo costuma ser o elo entre o identificador do sistema de origem e o cadastro persistido no Asaas.

Comportamento do endereço com CEP

Quando a requisição informa postalCode, o Asaas pode preencher automaticamente informações de endereço com base no CEP enviado.

Nesse cenário, o fluxo de integração pode ser simplificado, reduzindo a necessidade de preenchimento manual de atributos complementares do endereço.

Ainda assim, o número (addressNumber) continua sendo um dado relevante.

Clientes estrangeiros

O cadastro de clientes estrangeiros depende do ambiente e das permissões da conta.

• Em produção, essa funcionalidade precisa estar liberada
• Em sandbox, pode ser utilizada sem liberação prévia

❗️

Atenção

Para integrações que operam com pagadores internacionais, valide previamente se a conta de produção possui essa permissão ativa antes de colocar o fluxo em operação.

Cuidados em ambiente sandbox

As notificações por e-mail e SMS funcionam normalmente em sandbox.

❗️

Atenção

Evite utilizar dados reais de terceiros durante testes, pois o ambiente pode disparar comunicações reais.