Listar clientes

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/customers \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET

customers

Listar clientes

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/customers \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET /customers Faz parte do recurso Clientes — 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).

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.

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

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"

{
  "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
  }
}

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Query Parameters

page

integer

default:1

Página da listagem. Padrão: 1.

Required range: x >= 1

limit

integer

default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100

name

string | null

Busca parcial no nome, sem diferenciar maiúsculas de minúsculas. Um valor por requisição.

string | null

Busca parcial no e-mail, sem diferenciar maiúsculas de minúsculas. Um valor por requisição.

document

string | null

CPF, CNPJ ou passaporte. Correspondência exata — envie exatamente como foi cadastrado, com ou sem pontuação. Um valor por requisição.

documentType

enum<string> | null

Restringe ao tipo de documento: cpf, cnpj ou passport. Um valor por requisição.

Available options:

cpf,

cnpj,

passport

phone

string | null

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.

type

enum<string> | null

Restringe a pessoas físicas (individual) ou jurídicas (company).

Available options:

individual,

company

startDate

string<date-time> | null

Traz clientes criados a partir deste instante (ISO 8601 com timezone), inclusive.

endDate

string<date-time> | null

Traz clientes criados até este instante (ISO 8601 com timezone), inclusive.

sortDir

enum<string> | null

Ordem por data de cadastro: desc (mais recentes primeiro, padrão) ou asc.

Available options:

asc,

desc

Response

Lista paginada de clientes

data

object[]

Lista de registros retornados na página atual.

Show child attributes

pagination

object

Dados de paginação do resultado.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar clientes

Exemplo

Authorizations

Query Parameters

Response

​Exemplo

Authorizations

Query Parameters

Response

Exemplo