Clientes

Un Cliente es el registro canónico del comprador para un único Merchant. Almacena la identidad del comprador (correo electrónico, nombre, teléfono, documento fiscal) y una dirección de facturación, y ancla las transacciones, los pedidos y las suscripciones del comprador en un único registro.

Los clientes son únicos por correo electrónico por Merchant. La creación de un cliente es idempotente por correo electrónico: si ya existe un cliente con el mismo correo electrónico para el Merchant, Tokeflow devuelve el registro existente en lugar de crear un duplicado. Esto hace que la creación de clientes sea segura para reintentar desde flujos de checkout y de servidor a servidor.

El objeto cliente

Autenticación y alcances

Todos los endpoints de clientes requieren una clave secreta de Merchant (sk_live_mer_…). El Merchant se infiere a partir de la clave, por lo que nunca se pasa un merchant_id. Usa el alcance customers:read para operaciones de lectura y customers:write para creación/actualización.

Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx

POST/api/v1/customers

Crea un cliente para el Merchant resuelto a partir de la clave de API. Idempotente por correo electrónico: si ya existe un cliente con el mismo correo electrónico, se devuelve el registro existente con HTTP 200; un cliente nuevo devuelve HTTP 201.

Parámetros del cuerpo

Objeto billing_address

Solicitud

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1d8c2a-9b07-4f3e-9a1c-7e2b6d0c5a11" \
  -d '{
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "phone": "+5511999990000",
    "document_type": "cpf",
    "document_number": "123.456.789-00",
    "billing_address": {
      "line_1": "Av Paulista, 1000",
      "line_2": "Apto 42",
      "zip_code": "01310-100",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    },
    "metadata": { "source": "checkout_web" }
  }'

Respuesta 201 Created

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Cuando el correo electrónico ya existe, se devuelve el mismo cuerpo con estado 200 OK en lugar de 201.

GET/api/v1/customers

Lista los clientes del Merchant, del más reciente al más antiguo. Admite un filtro email y paginación.

Parámetros de consulta

Solicitud

curl -X GET "https://api.tokeflow.com/api/v1/customers?page=1&limit=20&email=joao@example.com" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "cust_a1b2c3d4e5",
      "merchant_id": "mrc_9f8e7d6c5b",
      "email": "joao@example.com",
      "name": "Joao da Silva",
      "phone": "+5511999990000",
      "document_type": "cpf",
      "metadata": { "source": "checkout_web" },
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET/api/v1/customers/:customerId

Recupera un único cliente por ID.

Parámetros de ruta

Solicitud

curl -X GET https://api.tokeflow.com/api/v1/customers/cust_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200 OK

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "phone": "+5511999990000",
    "document_type": "cpf",
    "metadata": { "source": "checkout_web" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Respuesta 404 Not Found

{
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Customer with ID \"cust_a1b2c3d4e5\" not found",
    "details": {},
    "request_id": "req_8f3c1a2b4d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

PATCH/api/v1/customers/:customerId

Actualiza un cliente. Todos los campos del cuerpo son opcionales; solo se modifican los campos enviados. Cambiar el email a uno ya utilizado por otro cliente del Merchant devuelve 409 Conflict.

Parámetros de ruta

Parámetros del cuerpo

Solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/customers/cust_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao P. da Silva",
    "phone": "+5511988887777",
    "metadata": { "source": "checkout_web", "tier": "gold" }
  }'

Respuesta 200 OK

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao P. da Silva",
    "phone": "+5511988887777",
    "document_type": "cpf",
    "metadata": { "source": "checkout_web", "tier": "gold" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T13:05:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T13:05:00.000Z"
}

Respuesta 409 Conflict

Se devuelve cuando el nuevo email ya pertenece a otro cliente del Merchant. El ID del cliente en conflicto se incluye en details.

{
  "error": {
    "type": "conflict_error",
    "code": "CUSTOMER_EMAIL_EXISTS",
    "message": "A customer with this email already exists for this merchant",
    "details": { "existing_customer_id": "cust_f6e5d4c3b2" },
    "request_id": "req_8f3c1a2b4d",
    "timestamp": "2026-01-15T13:05:00.000Z"
  }
}

DELETE/api/v1/customers/:customerId

Elimina permanentemente un cliente sin historial. Un cliente con cualquier suscripción, pedido, transacción, método de pago guardado o registro en un proveedor de pago es rechazado con 409, porque los clientes con actividad se conservan para informes y conciliación. Espera que el rechazo sea el resultado común: esto existe para un cliente creado por error — una errata, un duplicado, datos de prueba. El correo electrónico queda disponible para crear un cliente nuevo.

Parámetros de ruta

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/customers/cust_2f9a71d4 \
  -H "Authorization: Bearer sk_live_mer_…"

Ejemplo de respuesta — 204 No Content

Se devuelve un cuerpo vacío en caso de éxito.

Errores

Los endpoints de clientes usan el envoltorio de error estándar de Tokeflow. Casos comunes:

Relacionados

• Transacciones — cobrar a un cliente.
• Pedidos — agrupar las compras de un cliente.
• Suscripciones — facturación recurrente para un cliente.
• Autenticación — claves, alcances y encabezados.