Pular para o conteúdo principal
Customers representam os clientes (compradores) da sua company. Você cria um customer uma vez e reutiliza o id (cust_...) em transações, pagamentos e assinaturas. Todas as requisições exigem o header x-api-key. Veja Autenticação.

​
Endpoints

MétodoRotaDescrição
POST/customersCria um novo customer
GET/customersLista customers (paginado, com filtros)
GET/customers/:idBusca um customer por ID
PUT/customers/:idAtualiza um customer
DELETE/customers/:idRemove um customer (soft delete)

​
O objeto Customer

Campos aceitos na criação (POST) e atualização (PUT).
​
name
string
obrigatório
Nome do cliente. Mínimo de 2 caracteres.
​
email
string
obrigatório
E-mail do cliente. Precisa ser um e-mail válido.
​
type
enum
obrigatório
Tipo do cliente. Valores aceitos: individual, company.
​
document
string
obrigatório
Documento do cliente (CPF, CNPJ ou passaporte). Mínimo de 6 caracteres.
​
documentType
enum
padrão:"cpf"
Tipo do documento. Valores aceitos: cpf, cnpj, passport. Padrão: cpf.
​
phone
string
obrigatório
Telefone do cliente. Não pode ser vazio.
​
address
object
Endereço do cliente (opcional). Todos os campos internos são strings e podem ser null.
No address, cada campo é obrigatório dentro do objeto, mas aceita null. Ou seja: se você enviar address, inclua todas as 8 chaves (use null onde não tiver o dado). Se não tiver o endereço, simplesmente omita o address inteiro.

​
Criar customer

POST /customers — responde 201 Created.
Cria um novo customer associado à sua company. Este endpoint suporta idempotência: envie o header Idempotency-Key com um valor único por requisição para evitar criar customers duplicados em caso de retry. Veja Convenções.
​
x-api-key
string
obrigatório
Sua chave de API. Veja Autenticação.
​
Idempotency-Key
string
Chave única para garantir idempotência da requisição (opcional).
curl -X POST https://api.sandbox.z2pay.com/customers \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria.silva@example.com",
    "type": "individual",
    "document": "12345678909",
    "documentType": "cpf",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310-100",
      "country": "BR"
    }
  }'
Resposta 201
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.silva@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511999998888",
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310-100",
    "country": "BR"
  },
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T14:30:00.000Z"
}

​
Listar customers

GET /customers — responde 200 OK com lista paginada.
Retorna a lista paginada de customers da sua company, com suporte a filtros e ordenação.

​
Parâmetros de query

Todos os filtros são opcionais e passados via query string. Quando informados, valores de texto fazem busca parcial.
​
name
string
Filtra por nome.
​
email
string
Filtra por e-mail.
​
document
string
Filtra por documento.
​
documentType
enum
Filtra por tipo de documento: cpf, cnpj ou passport.
​
phone
string
Filtra por telefone.
​
type
enum
Filtra por tipo de cliente: individual ou company.
​
search
string
Busca livre.
​
customerSearch
string
Busca combinada (ILIKE) em name, email e document do cliente.
​
startDate
string
Data inicial do intervalo de criação. Formato ISO 8601 com timezone (ex: 2026-01-01T00:00:00Z).
​
endDate
string
Data final do intervalo de criação. Formato ISO 8601 com timezone (ex: 2026-01-31T23:59:59Z).
​
sortBy
enum
Campo de ordenação. Valores: name, createdAt, updatedAt.
​
sortDir
enum
Direção da ordenação. Valores: asc, desc.

​
Paginação

​
page
integer
padrão:"1"
Número da página (mínimo 1).
​
limit
integer
padrão:"20"
Quantidade de itens por página (mínimo 1, máximo 100).
Os parâmetros de data devem usar ISO 8601 com timezone. Datas só com dia (YYYY-MM-DD) ou no formato DD/MM/YYYY são rejeitadas. Veja Convenções.
curl -G https://api.sandbox.z2pay.com/customers \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "customerSearch=maria" \
  --data-urlencode "type=individual" \
  --data-urlencode "sortBy=createdAt" \
  --data-urlencode "sortDir=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"
Resposta 200
{
  "data": [
    {
      "id": "cust_8f3k2m9q1w7r5t0y",
      "name": "Maria Silva",
      "email": "maria.silva@example.com",
      "type": "individual",
      "document": "12345678909",
      "documentType": "cpf",
      "phone": "+5511999998888",
      "createdAt": "2026-06-24T14:30:00.000Z",
      "updatedAt": "2026-06-24T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
Os metadados de paginação vêm aninhados em um objeto pagination (page, limit, total e totalPages). Esse envelope é o padrão da plataforma — veja Convenções.

​
Buscar customer por ID

GET /customers/:id — responde 200 OK.
Retorna os dados completos de um customer específico.
​
id
string
obrigatório
ID do customer (ex: cust_8f3k2m9q1w7r5t0y).
curl https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.silva@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511999998888",
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310-100",
    "country": "BR"
  },
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T14:30:00.000Z"
}
Se o customer não existir (ou tiver sido removido), a API responde 404 Not Found. Veja a lista de status em Erros.

​
Atualizar customer

PUT /customers/:id — responde 200 OK.
Atualiza os dados de um customer existente. Todos os campos do objeto Customer são opcionais na atualização — envie apenas os que deseja alterar. Este endpoint é idempotente.
​
id
string
obrigatório
ID do customer a ser atualizado.
curl -X PUT https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511988887777",
    "email": "maria.s@example.com"
  }'
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.s@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511988887777",
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T15:10:00.000Z"
}
Se o customer não existir, a API responde 404 Not Found. Veja Erros.

​
Remover customer

DELETE /customers/:id — responde 200 OK.
Remove um customer via soft delete: o registro não é apagado de fato, apenas marcado como removido. A resposta retorna a entidade com o campo deletedAt preenchido. Este endpoint é idempotente.
​
id
string
obrigatório
ID do customer a ser removido.
curl -X DELETE https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.s@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511988887777",
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T15:10:00.000Z",
  "deletedAt": "2026-06-24T16:00:00.000Z"
}
Se o customer não existir, a API responde 404 Not Found. Veja Erros.

​
Veja também

Transactions

Crie transações usando o customer como comprador.

Payments

Pagamentos vinculados às transações do customer.

Assinaturas

Cobranças recorrentes para um customer.

Convenções

Paginação, idempotência e formatos de data.