Cadastro de clientes

O cadastro de clientes é o primeiro passo para criar cobranças vinculadas a um pagador no Asaas.

Ao criar um cliente, a API retorna um identificador único, como cus_000005219613. Esse ID deve ser armazenado pela sua aplicação e utilizado em operações posteriores, como criação de cobranças, assinaturas, consultas e atualizações cadastrais.

Quando utilizar

Crie um cliente quando sua integração precisar registrar um pagador para:

• criar cobranças;
• criar assinaturas;
• reutilizar dados cadastrais em pagamentos futuros;
• consultar ou atualizar informações do pagador;
• conciliar clientes entre o seu sistema e o Asaas.

Caso o cliente já tenha sido criado anteriormente, reutilize o ID salvo na sua aplicação ou consulte o cadastro antes de criar um novo.

Fluxo básico

Criar ou consultar cliente
↓
Armazenar o ID do cliente
↓
Criar cobrança usando o campo customer
↓
Acompanhar o status da cobrança

Criar cliente

POST /v3/customers
Confira a referência completa deste endpoint

{
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792",
  "mobilePhone": "4799376637"
}

Campos importantes

Alguns campos ajudam na identificação, comunicação e conciliação do cliente:

• name: nome do cliente;
• cpfCnpj: CPF ou CNPJ do cliente;
• email: e-mail usado em comunicações;
• mobilePhone: celular do cliente;
• externalReference: identificador do cliente no seu sistema;
• notificationDisabled: define se o cliente receberá notificações;
• additionalEmails: e-mails adicionais para notificações.

Consulte a referência do endpoint para conferir todos os campos aceitos, obrigatoriedades e formatos esperados.

Resposta da criação

Ao criar um cliente, a API retorna um objeto com os dados cadastrados e o identificador único do cliente.

Exemplo simplificado:

{
  "id": "cus_000005219613",
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792"
}

O valor retornado em id deve ser enviado no campo customer ao criar cobranças para esse cliente.

Clientes duplicados

Você pode consultar clientes existentes pelo endpoint Listar Clientes.

Essa validação é recomendada em fluxos com:

• reprocessamento de pedidos;
• filas assíncronas;
• retentativas automáticas;
• integrações que recebem o mesmo cliente por mais de um canal.

Boas práticas

• Armazene o ID do cliente retornado pela API.
• Use externalReference para relacionar o cliente ao cadastro do seu sistema.
• Valide CPF/CNPJ, e-mail e telefone antes de enviar a requisição.
• Evite criar um novo cliente a cada cobrança para o mesmo pagador.
• Antes de repetir uma requisição com erro ou timeout, verifique se o cliente já foi criado.

Referência da API