Saltar al contenido principal
Customers representan los clientes (compradores) de tu company. Creas un customer una vez y reutilizas el id (cust_...) en transacciones, pagos y suscripciones. Todas las solicitudes requieren el header x-api-key. Consulta Autenticación.

​
Endpoints

MétodoRutaDescripción
POST/customersCrea un nuevo customer
GET/customersLista customers (paginado, con filtros)
GET/customers/:idBusca un customer por ID
PUT/customers/:idActualiza un customer
DELETE/customers/:idElimina un customer (soft delete)

​
El objeto Customer

Campos aceptados en la creación (POST) y actualización (PUT).
​
name
string
requerido
Nombre del cliente. Mínimo 2 caracteres.
​
email
string
requerido
Correo electrónico del cliente. Debe ser un email válido.
​
type
enum
requerido
Tipo de cliente. Valores aceptados: individual, company.
​
document
string
requerido
Documento del cliente (CPF, CNPJ o pasaporte). Mínimo 6 caracteres.
​
documentType
enum
predeterminado:"cpf"
Tipo de documento. Valores aceptados: cpf, cnpj, passport. Por defecto: cpf.
​
phone
string
requerido
Teléfono del cliente. No puede estar vacío.
​
address
object
Dirección del cliente (opcional). Todos los campos internos son strings y pueden ser null.
En address, cada campo es obligatorio dentro del objeto, pero acepta null. Es decir: si envías address, incluye las 8 claves (usa null donde no tengas el dato). Si no tienes la dirección, simplemente omite el objeto address completo.

​
Crear customer

POST /customers — responde 201 Created.
Crea un nuevo customer asociado a tu company. Este endpoint admite idempotencia: envía el header Idempotency-Key con un valor único por solicitud para evitar crear customers duplicados en caso de reintento. Consulta Convenciones.
​
x-api-key
string
requerido
Tu clave de API. Consulta Autenticación.
​
Idempotency-Key
string
Clave única para garantizar la idempotencia de la solicitud (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 con lista paginada.
Devuelve la lista paginada de customers de tu company, con soporte para filtros y ordenación.

​
Parámetros de query

Todos los filtros son opcionales y se pasan como query string. Cuando se especifican, los valores de texto realizan búsqueda parcial.
​
name
string
Filtra por nombre.
​
email
string
Filtra por correo electrónico.
​
document
string
Filtra por documento.
​
documentType
enum
Filtra por tipo de documento: cpf, cnpj o passport.
​
phone
string
Filtra por teléfono.
​
type
enum
Filtra por tipo de cliente: individual o company.
​
search
string
Búsqueda libre.
​
customerSearch
string
Búsqueda combinada (ILIKE) en name, email y document del cliente.
​
startDate
string
Fecha de inicio del intervalo de creación. Formato ISO 8601 con timezone (ej: 2026-01-01T00:00:00Z).
​
endDate
string
Fecha de fin del intervalo de creación. Formato ISO 8601 con timezone (ej: 2026-01-31T23:59:59Z).
​
sortBy
enum
Campo de ordenación. Valores: name, createdAt, updatedAt.
​
sortDir
enum
Dirección de ordenación. Valores: asc, desc.

​
Paginación

​
page
integer
predeterminado:"1"
Número de página (mínimo 1).
​
limit
integer
predeterminado:"20"
Cantidad de ítems por página (mínimo 1, máximo 100).
Los parámetros de fecha deben usar ISO 8601 con timezone. Fechas solo con día (YYYY-MM-DD) o en formato DD/MM/YYYY son rechazadas. Consulta Convenciones.
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
  }
}
Los metadatos de paginación vienen anidados en un objeto pagination (page, limit, total y totalPages). Este envelope es el estándar de la plataforma — consulta Convenciones.

​
Buscar customer por ID

GET /customers/:id — responde 200 OK.
Devuelve los datos completos de un customer específico.
​
id
string
requerido
ID del customer (ej: 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"
}
Si el customer no existe (o ha sido eliminado), la API responde 404 Not Found. Consulta la lista de estados en Errores.

​
Actualizar customer

PUT /customers/:id — responde 200 OK.
Actualiza los datos de un customer existente. Todos los campos del objeto Customer son opcionales en la actualización — envía solo los que deseas modificar. Este endpoint es idempotente.
​
id
string
requerido
ID del customer a actualizar.
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"
}
Si el customer no existe, la API responde 404 Not Found. Consulta Errores.

​
Eliminar customer

DELETE /customers/:id — responde 200 OK.
Elimina un customer mediante soft delete: el registro no se borra físicamente, solo se marca como eliminado. La respuesta devuelve la entidad con el campo deletedAt completado. Este endpoint es idempotente.
​
id
string
requerido
ID del customer a eliminar.
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"
}
Si el customer no existe, la API responde 404 Not Found. Consulta Errores.

​
Ver también

Transactions

Crea transacciones usando el customer como comprador.

Payments

Pagos vinculados a las transacciones del customer.

Suscripciones

Cobros recurrentes para un customer.

Convenciones

Paginación, idempotencia y formatos de fecha.