Clientes

Referência

Um cliente é o cadastro do pagador (nome, documento, contato e endereço) reaproveitado em cobranças e assinaturas sem precisar redigitar os dados a cada venda. Este guia explica o que identifica um cliente dentro da sua conta, como a criação trata duplicidade e o que trava (ou não) a exclusão.

Remover cliente é definitivo. Diferente da subconta, que usa soft-delete, o DELETE /v1/customers/:customerId apaga o registro do banco de dados. Não há como restaurar depois.

O que é um cliente

O cadastro de cliente existe para você não precisar coletar nome, documento, contato e endereço a cada nova cobrança ou assinatura. Uma vez criado, o customerId pode ser referenciado nas rotas de cobrança e assinatura, e o endereço cadastrado já entra pronto para a emissão de nota fiscal.

Não existe uma rota separada para criar assinatura a partir de um cliente. A ligação entre os dois nasce quando uma cobrança ou um checkout com produto recorrente é pago referenciando aquele documento. Veja Assinaturas: visão geral para o fluxo completo.

Campos e identificadores

Campo	Descrição
`customerId`	Identificador único do cliente, gerado pela ValidaPay. Também vem como id.
`document`	CPF (11 dígitos) ou CNPJ (14 dígitos), só números. Chave do cliente dentro da conta, imutável após criado.
`name`	Nome completo ou razão social. Único campo obrigatório além do documento e do telefone.
`phone`	Telefone em E.164 com DDI 55 (ex.: 5511987654321).
`email`	Opcional na criação. Quando ausente, é gravado internamente como "-".
`additionalEmails`	Opcional, só em atualização: e-mails extras que também recebem cobranças e faturas.
`address`	Endereço opcional. Quando enviado, o cityCode (código IBGE do município, necessário para NFS-e) é resolvido a partir do CEP.
`status`	ACTIVE na criação. Passa a refletir automaticamente o status da assinatura vinculada quando o cliente tem uma.

Documento como chave

document é o que identifica um cliente dentro da sua conta, não email, que é opcional e pode até ficar ausente. Ao criar um cliente, a API sempre verifica se já existe alguém com o mesmo CPF/CNPJ nesta conta:

upsert ausente ou false (padrão)

Documento já cadastrado → retorna 200 com o cliente existente, sem duplicar e sem erro.

upsert: true

Documento já cadastrado → retorna erro 400 CUSTOMER_ALREADY_EXISTS.

{
  "customer": {
    "customerId": "cus_xxx",
    "id": "cus_xxx",
    "name": "Alexandre Souza",
    "document": "11144477735",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "accountId": "460851686",
    "status": "ACTIVE",
    "createdAt": "2026-08-28T12:00:00.000Z"
  }
}

{
  "error": {
    "message": "Já existe um cliente cadastrado com este documento",
    "code": "CUSTOMER_ALREADY_EXISTS",
    "details": null,
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}

O mesmo CPF/CNPJ pode existir como cliente em contas diferentes: a checagem de duplicidade é sempre por documento + conta autenticada, nunca global.

Atualizar cliente

•PATCH /v1/customers/:customerId altera só os campos enviados: name, email, additionalEmails, phone ou address.
•document não pode ser alterado. Enviar um valor diferente do já cadastrado retorna DOCUMENT_UPDATE_NOT_ALLOWED.
•Quando address é enviado, ele substitui inteiro o endereço padrão anterior. Não faz merge campo a campo.

Excluir cliente

DELETE /v1/customers/:customerId remove o registro de verdade. Ao contrário da subconta, não há soft-delete aqui. A exclusão é recusada com 400 CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS quando o cliente tiver qualquer assinatura (recorrente ou venda avulsa, que também é registrada como assinatura) cujo status não seja EXPIRED, CANCELED ou COMPLETED. O details da resposta lista cada assinatura em aberto.

{
  "error": {
    "message": "Cliente possui 1 assinatura(s) em aberto. Cancele antes de excluir.",
    "code": "CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS",
    "details": [
      { "subscriptionId": "sub_xxx", "status": "ACTIVE", "interval": "MONTHLY" }
    ],
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}

Consultas por documento e listagem

Existem duas formas de encontrar um cliente, para dois casos de uso diferentes:

Buscar Cliente por Documento

GET /v1/customers?lookupDocument=...: correspondência exata pelo CPF/CNPJ completo, já retornando o endereço padrão junto. Ideal para pré-preencher um checkout a partir do documento digitado.

Listar Clientes

GET /v1/customers?search=...: busca parcial simultânea em nome, e-mail e documento, com paginação por cursor. Ideal para uma tela de seleção onde o usuário ainda está digitando.

Quando o documento buscado não está cadastrado, a busca por documento não retorna erro. Vem 200 com ambos os campos em null:

{
  "customer": null,
  "address": null
}

Detalhe do cliente

GET /v1/customers/:customerId traz a visão consolidada: todos os endereços cadastrados e cada assinatura vinculada já com seus itens, ciclos de cobrança, faturas e cobranças de cada ciclo, mais um resumo de ltv (total bruto, total líquido e número de ciclos pagos). É a mesma origem de dados usada em Assinaturas: visão geral.

O que a API de clientes permite

Operação	Descrição
Criar Cliente	Cadastra pelo CPF/CNPJ, com endereço opcional e resolução automática de cityCode.
Listar Clientes	Busca parcial por nome, e-mail ou documento, com paginação por cursor.
Buscar Cliente por Documento	Busca exata por CPF/CNPJ, já com o endereço padrão.
Detalhar Cliente	Dados completos: endereços, assinaturas, ciclos, faturas e LTV.
Atualizar Cliente	Altera nome, e-mail, telefone ou endereço. Documento é imutável.
Remover Cliente	Exclusão definitiva, bloqueada quando há vínculos ativos.

Erros comuns

code	Status	Quando acontece
`INVALID_DATA`	400	Corpo não passou na validação (Zod): documento inválido, telefone fora do E.164, CEP com menos de 8 dígitos, UF inexistente etc.
`CUSTOMER_ALREADY_EXISTS`	400	upsert: true e já existe cliente com esse documento nesta conta.
`CUSTOMER_NOT_FOUND`	404	customerId não existe.
`FORBIDDEN`	401	O cliente existe, mas pertence a outra conta.
`DOCUMENT_UPDATE_NOT_ALLOWED`	400	A atualização tentou enviar um document diferente do já cadastrado.
`DOCUMENT_REQUIRED`	400	Busca por documento (lookupDocument) sem informar o valor.
`CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS`	400	Cliente tem ao menos uma assinatura que não está EXPIRED, CANCELED ou COMPLETED (inclui venda avulsa ainda pendente). Cancele antes de excluir.

Perguntas frequentes

O documento precisa ser único em toda a ValidaPay?▾

Não, só dentro da sua conta. O mesmo CPF/CNPJ pode existir como cliente em contas diferentes: a checagem de duplicidade em Criar Cliente é sempre por documento + conta autenticada.

O que acontece se eu tentar cadastrar um cliente com um documento que já existe?▾

Por padrão (upsert não enviado ou false), a API não cria um segundo registro nem retorna erro: devolve 200 com o cadastro já existente. Só retorna erro 400 (CUSTOMER_ALREADY_EXISTS) se você enviar upsert: true. Nesse caso a intenção é garantir que a chamada falhe quando o cliente já existe, em vez de devolvê-lo silenciosamente.

Posso mudar o CPF/CNPJ de um cliente já cadastrado?▾

Não. PATCH Atualizar Cliente recusa qualquer document diferente do já salvo, com DOCUMENT_UPDATE_NOT_ALLOWED. Para corrigir um documento errado, é preciso remover o cliente (se não houver vínculos) e cadastrar de novo.

Remover um cliente é reversível?▾

Não. Ao contrário da subconta (que usa soft-delete), DELETE Remover Cliente apaga o registro definitivamente do banco de dados. Não há como restaurar depois: se precisar do histórico, garanta que ele já esteja consultado antes de excluir.

Uma venda avulsa (ONE_TIME) já paga também bloqueia a exclusão?▾

Não. Uma venda avulsa vira COMPLETED depois de paga, e esse status não bloqueia. Só bloqueia enquanto a assinatura (recorrente ou avulsa) estiver em qualquer status diferente de EXPIRED, CANCELED ou COMPLETED — por exemplo PENDING, ACTIVE ou PAST_DUE.

Qual a diferença entre Buscar Cliente por Documento e Listar Clientes?▾

Buscar Cliente por Documento (lookupDocument) é uma busca exata por CPF/CNPJ que já retorna o endereço padrão junto, pronta para pré-preencher um formulário de checkout. Responde 200 com customer: null quando não encontra, sem gerar erro. Listar Clientes é uma listagem paginada com busca parcial (search) por nome, e-mail ou documento, pensada para telas de seleção onde o usuário ainda está digitando.

Próximos passos

Criar Cliente Buscar Cliente por Documento Detalhar Cliente (assinaturas, ciclos e LTV)Assinaturas: visão geral

Essa página foi útil?