> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar clientes
> Lista paginada de clientes, com filtros por nome, e-mail, documento, telefone, tipo e data de cadastro.
`GET /customers`
Faz parte do recurso [Clientes](/pt-BR/customers) — o objeto e o que o torna único estão lá.
Retorna uma lista paginada, **por data de cadastro**, do mais recente para o mais antigo — use
`sortDir=asc` para inverter. Todos os filtros são opcionais e podem ser combinados; quando você
informa mais de um, o cliente precisa satisfazer **todos**. As datas seguem **ISO 8601 com
timezone** (veja [Convenções](/pt-BR/convencoes)).
**A resposta é paginada, e o padrão é 20 por página.** Confira `pagination.totalPages` antes de
concluir que a lista acabou — nada no corpo avisa que houve corte além do próprio `pagination`. O
`limit` aceita até `100`.
**Filtro com valor inválido é rejeitado, não ignorado.** `?type=xpto` responde **400** com
`error.issues[]` apontando o campo e os valores aceitos.
O formato do erro e a lista de códigos estão em [Erros](/pt-BR/erros).
**Nem todo filtro casa do mesmo jeito.** `name`, `email` e `phone` fazem busca parcial — `mari`
encontra "Maria" e "Marina". Já `document` exige o valor **exato**: um CPF parcial não retorna
nada. Se você guarda o documento do comprador, ele é o caminho mais confiável para reencontrar um
cliente — e é também o que a API usa para barrar duplicidade.
Em `phone`, a pontuação é ignorada dos dois lados, então `11999998888` e `(11) 99999-8888`
chegam ao mesmo cliente.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/customers \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "type=individual" \
--data-urlencode "name=maria" \
--data-urlencode "sortDir=desc" \
--data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "cust_g5kcy5ueag2hatims8e5qx7g6",
"name": "Maria Silva",
"email": "maria.silva@example.com",
"type": "individual",
"document": "12345678909",
"documentType": "cpf",
"phone": "+5511999998888",
"address": {
"street": "Rua das Flores",
"number": "123",
"complement": "Apto 45",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"postalCode": "01001000",
"country": "BR"
},
"createdAt": "2026-06-24T14:30:00.000Z",
"updatedAt": "2026-06-24T14:30:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /customers
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/customers:
get:
tags:
- Customers
summary: Listar clientes
description: >-
Retorna lista paginada de clientes, com filtros por nome, e-mail,
documento, telefone, tipo e período de criação
operationId: CustomerController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: name
in: query
required: false
description: >-
Busca parcial no nome, sem diferenciar maiúsculas de minúsculas. Um
valor por requisição.
schema:
type: string
nullable: true
description: >-
Busca parcial no nome, sem diferenciar maiúsculas de minúsculas.
Um valor por requisição.
- name: email
in: query
required: false
description: >-
Busca parcial no e-mail, sem diferenciar maiúsculas de minúsculas.
Um valor por requisição.
schema:
type: string
nullable: true
description: >-
Busca parcial no e-mail, sem diferenciar maiúsculas de minúsculas.
Um valor por requisição.
- name: document
in: query
required: false
description: >-
CPF, CNPJ ou passaporte. Correspondência **exata** — envie
exatamente como foi cadastrado, com ou sem pontuação. Um valor por
requisição.
schema:
type: string
nullable: true
description: >-
CPF, CNPJ ou passaporte. Correspondência **exata** — envie
exatamente como foi cadastrado, com ou sem pontuação. Um valor por
requisição.
- name: documentType
in: query
required: false
description: >-
Restringe ao tipo de documento: `cpf`, `cnpj` ou `passport`. Um
valor por requisição.
schema:
type: string
enum:
- cpf
- cnpj
- passport
nullable: true
description: >-
Restringe ao tipo de documento: `cpf`, `cnpj` ou `passport`. Um
valor por requisição.
- name: phone
in: query
required: false
description: >-
Busca parcial no telefone. A pontuação é ignorada nos dois lados,
então `11999998888` e `(11) 99999-8888` encontram o mesmo cliente.
Um valor por requisição.
schema:
type: string
nullable: true
description: >-
Busca parcial no telefone. A pontuação é ignorada nos dois lados,
então `11999998888` e `(11) 99999-8888` encontram o mesmo cliente.
Um valor por requisição.
- name: type
in: query
required: false
description: Restringe a pessoas físicas (`individual`) ou jurídicas (`company`).
schema:
type: string
enum:
- individual
- company
nullable: true
description: >-
Restringe a pessoas físicas (`individual`) ou jurídicas
(`company`).
- name: startDate
in: query
required: false
description: >-
Traz clientes criados a partir deste instante (ISO 8601 com
timezone), inclusive.
schema:
type: string
format: date-time
nullable: true
description: >-
Traz clientes criados a partir deste instante (ISO 8601 com
timezone), inclusive.
- name: endDate
in: query
required: false
description: >-
Traz clientes criados até este instante (ISO 8601 com timezone),
inclusive.
schema:
type: string
format: date-time
nullable: true
description: >-
Traz clientes criados até este instante (ISO 8601 com timezone),
inclusive.
- name: sortDir
in: query
required: false
description: >-
Ordem por data de cadastro: `desc` (mais recentes primeiro, padrão)
ou `asc`.
schema:
type: string
enum:
- asc
- desc
nullable: true
description: >-
Ordem por data de cadastro: `desc` (mais recentes primeiro,
padrão) ou `asc`.
responses:
'200':
description: Lista paginada de clientes
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
name:
type: string
description: Nome do registro.
email:
type: string
description: E-mail de contato.
type:
type: string
description: >-
Tipo de lançamento (sale, refund, chargeback,
withdrawal, fee, etc)
document:
type: string
description: Documento (CPF ou CNPJ) do titular.
documentType:
type: string
description: 'Tipo de documento: cpf ou cnpj.'
phone:
type: string
description: Telefone de contato.
address:
type: object
nullable: true
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: Endereço do cliente.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: cust_kyz6cwnbm55aax1lhxewn01o4
name: Maria Oliveira
email: maria.oliveira@example.com
type: individual
document: '12345678909'
documentType: cpf
phone: '+5511987654321'
address:
street: Av. Paulista
number: '1578'
complement: Apto 142
neighborhood: Bela Vista
city: São Paulo
state: SP
postalCode: 01310-200
country: BR
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
- id: cust_ml658pjgratcj1qd1ukm6y7bh
name: Tech Solutions LTDA
email: financeiro@techsolutions.com.br
type: company
document: '12345678000199'
documentType: cnpj
phone: '+5511933334444'
address: null
createdAt: '2025-06-20T09:12:05.000Z'
updatedAt: '2025-06-25T18:30:11.000Z'
pagination:
page: 1
limit: 20
total: 2
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````