Cadastro de clientes

Antes de criar uma cobrança ou assinatura, cadastre o pagador como cliente no Asaas.

Ao concluir a criação, a API retorna um identificador único, como cus_000005219613. Armazene esse ID na sua aplicação para utilizá-lo em cobranças, assinaturas, consultas e atualizações futuras.

Quando utilizar

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

• criar cobranças;
• criar assinaturas;
• reutilizar os dados cadastrais em operações futuras;
• consultar ou atualizar informações do pagador;
• relacionar o cadastro do Asaas ao cliente do seu sistema.

Caso o cliente já tenha sido cadastrado, reutilize o ID armazenado pela sua aplicação ou consulte os clientes existentes antes de criar um novo registro.

Antes de começar

Defina:

• quais dados do cliente serão enviados;
• qual identificador do seu sistema será informado em externalReference;
• se o cliente receberá notificações do Asaas;
• onde o ID retornado será armazenado;
• como sua integração evitará cadastros duplicados.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Receber os dados do pagador"] --> B{"O cliente já possui ID no Asaas?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Reutilizar o ID armazenado"]
    BNao --> D["Consultar ou cadastrar o cliente"]
    D --> E["Armazenar o ID retornado"]

    C --> F["Relacionar o ID ao cadastro interno"]
    E --> F

    F --> G["Criar cobrança usando o campo customer"]
    G --> H["Acompanhar o pagamento"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

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

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

1. Verifique se o cliente já existe

Antes de criar um cadastro, verifique se sua aplicação já possui o ID do cliente no Asaas.

Quando necessário, consulte os clientes existentes pelo endpoint:

Listar clientes

Essa verificação é especialmente importante em fluxos com:

• retentativas automáticas;
• reprocessamento de pedidos;
• filas assíncronas;
• clientes recebidos por diferentes canais;
• operações que podem ser executadas mais de uma vez.

2. Crie o cliente

Envie uma requisição para:

POST /v3/customers

Consulte o endpoint: Criar novo cliente.

Exemplo de requisição

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

Campos importantes

Consulte a referência do endpoint para verificar todos os campos aceitos, formatos e regras de preenchimento.

3. Armazene o ID retornado

Após criar o cliente, a API retorna os dados cadastrados e o identificador do recurso.

Exemplo simplificado de resposta

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

Armazene o valor retornado em id.

Esse identificador deve ser enviado no campo customer ao criar uma cobrança ou assinatura para o cliente.

Exemplo:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 100,
  "dueDate": "2026-08-15"
}

Consulte o endpoint: Criar nova cobrança.

Evite clientes duplicados

Uma estratégia recomendada é:

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Receber os dados do pagador"] --> B["Verificar o vínculo salvo na aplicação"]
    B --> C{"Cliente já possui ID?"}

    C --> CSim(("Sim"))
    C --> CNao(("Não"))

    CSim --> D["Reutilizar o ID"]
    CNao --> E["Consultar ou criar o cliente"]
    E --> F["Armazenar o ID retornado"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

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

    class CSim respostaSim
    class CNao respostaNao

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

Não crie um novo cliente para cada cobrança do mesmo pagador.

Confirme o resultado

Após a requisição, confirme se:

• a resposta retornou o campo id;
• os dados foram cadastrados corretamente;
• o ID foi armazenado pela sua aplicação;
• o cadastro foi relacionado ao cliente do seu sistema;
• as configurações de notificação estão de acordo com a jornada desejada.

Caso o cliente não seja criado

Verifique se:

• os dados estão no formato esperado;
• o CPF ou CNPJ foi informado corretamente;
• o e-mail e o telefone são válidos;
• a URL e a chave de API pertencem ao mesmo ambiente;
• todos os campos obrigatórios foram enviados;
• o cliente não foi criado em uma tentativa anterior.

Boas práticas

• Armazene o ID retornado pela API.
• Utilize externalReference para facilitar a conciliação.
• Valide CPF ou CNPJ, e-mail e telefone antes do envio.
• Reutilize o cliente nas próximas cobranças e assinaturas.
• Não dependa apenas de CPF, CNPJ ou e-mail como vínculo interno.
• Registre a relação entre o ID do Asaas e o ID da sua aplicação.
• Revise as configurações de notificação para evitar comunicações duplicadas.

Referência da API

Próximos passos

• Conheça o fluxo de cobranças
• Crie uma nova cobrança
• Crie cobranças via boleto
• Crie cobranças via Pix
• Crie cobranças via cartão de crédito
• Configure as notificações
• Configure Webhooks