Skip to main content
GET
Esta rota devolve, página a página, os clientes (objeto customer) cadastrados na sua conta. Use para montar uma tela de clientes no seu sistema, para encontrar o id de um cliente antes de cobrar ou registrar um cartão e para conferir se uma pessoa já tem cadastro antes de criar outro.

Quando usar

Antes de chamar

  • Tenha uma chave secreta (sk_) válida (Credenciais e ambientes).
  • A rota lista os clientes da conta dona da chave. Com a chave de teste, você vê os clientes do ambiente de testes.

Parâmetros de consulta

Todos os parâmetros são opcionais. Sem nenhum filtro, a rota devolve a primeira página com até 10 clientes, dos mais recentes para os mais antigos.
Busca por nome, e-mail, documento ou telefone. Ex.: joao.
string
Filtra pelo e-mail exato. Ex.: [email protected].
string
Filtra pelo número do documento. Ex.: 52998224725.
integer
default:"1"
Número da página. Começa em 1. Valor menor que 1 ou não numérico volta ao padrão.
integer
default:"10"
Quantidade de itens por página. Valor menor que 1 ou não numérico volta ao padrão.
O tamanho da página vai em size. Um parâmetro limit é ignorado sem erro: limit=50 continua devolvendo 10 itens.
Para o desenvolvedor: search serve para busca livre (uma caixa de pesquisa, por exemplo). Para checar se um cliente já existe antes de criar outro, prefira email ou documentId, que são filtros diretos. As regras gerais de paginação estão em Paginação, ordenação e idempotência.

Respostas

A resposta usa o mesmo envelope plano das outras listagens paginadas da API.
object[]
Clientes da página atual.
integer
Total de clientes encontrados com os filtros enviados.
integer
Página atual.
integer
Itens por página.
integer
Total de páginas.
Em validação (V-37): os campos de cada cliente em data e o exemplo de resposta estão retidos até a correção desta listagem pelo time técnico.
Para o negócio: um cliente pode nascer de duas formas: pelo cadastro direto em Criar cliente ou automaticamente, quando uma cobrança ou assinatura recebe nome e e-mail sem um id. Esta rota é a forma de a equipe encontrar um cadastro e recuperar o identificador dele para as operações seguintes, como registrar um cartão.

Erros comuns

Veja também

Guia de clientes

Quando cadastrar clientes e como eles se ligam a cartões e assinaturas.

Criar cliente

Cadastro com nome, e-mail e documento.

Consultar cliente

Dados de um cliente pelo id.

Visão geral de assinaturas

O cliente como primeiro passo da cobrança recorrente.