Clientes del Merchant

Estos endpoints respaldan la pantalla de clientes del Dashboard para un único Merchant: listar pagadores con búsqueda y filtros, abrir uno para ver todo su detalle y actualizar o eliminar un registro.

Un cliente agrupa todo lo que un pagador posee dentro de este Merchant — instrumentos de pago guardados, pedidos y suscripciones. Los clientes nunca cruzan los límites de un Merchant, por lo que la misma persona que compra en dos de tus Merchants son dos registros de cliente independientes.

El objeto cliente

Devuelto por los endpoints de listado y recuperación de esta página.

Endpoints

GET/api/v1/merchant/customers

Lista los clientes del Merchant.

Parámetros de consulta

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchant/customers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "merchant_id=mrc_8a3f12d9" \
  --data-urlencode "search=string"

DELETE/api/v1/merchant/customers/:id

Elimina permanentemente un cliente. Cancela todas las suscripciones que aún no estén canceladas o vencidas, revoca todos los métodos de pago guardados — eliminando los datos de la tarjeta almacenados — y luego retira al cliente. Esto no se puede deshacer. El cliente sigue siendo recuperable mediante GET /:id, de modo que su historial permanece revisable, pero sale de la lista de clientes y ya no puede usarse para nuevas operaciones, y su correo electrónico vuelve a estar disponible. Ten en cuenta que esto difiere del DELETE en la superficie de clave de API (/customers/:customerId), que en su lugar rechaza con 409 cuando un cliente tiene algún historial.

Parámetros de ruta

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/customers/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Ejemplo de respuesta — 200

{
  "id": "cust_123",
  "object": "customer",
  "deleted": true
}

GET/api/v1/merchant/customers/:id

Obtiene un cliente por ID.

Parámetros de ruta

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchant/customers/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "merchant_id": "mrc_8a3f12d9",
  "merchant_name": "Acme Store",
  "name": "Jane Buyer",
  "email": "jane@example.com",
  "phone": "+5511987654321",
  "document_type": "12345678909",
  "document_number": "12345678909",
  "metadata": {},
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "deleted": false,
  "payment_instruments": [
    {
      "id": "obj_1a2b3c4d",
      "instrument_type": "standard",
      "last4": "string",
      "brand": "string",
      "card_type": "standard",
      "exp_month": 1,
      "exp_year": 1,
      "external_wallet_id": "string",
      "status": "active",
      "is_default": true,
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "linked_subscriptions": [
    {}
  ],
  "linked_orders": [
    {
      "id": "obj_1a2b3c4d",
      "status": "active",
      "total_amount": 15000,
      "currency": "BRL",
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "external_references": [
    {
      "source_type": "standard",
      "connector_name": "Acme Store",
      "external_id": "string"
    }
  ]
}

PATCH/api/v1/merchant/customers/:id

Actualiza un cliente.

Parámetros de ruta

Campos de la solicitud

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/customers/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "email": "jane@example.com",
    "phone": "+5511987654321",
    "document_type": "cpf",
    "document_number": "12345678909"
  }'

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "merchant_id": "mrc_8a3f12d9",
  "merchant_name": "Acme Store",
  "name": "Jane Buyer",
  "email": "jane@example.com",
  "phone": "+5511987654321",
  "document_type": "12345678909",
  "document_number": "12345678909",
  "metadata": {},
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "deleted": false
}

Errores

Los errores usan el envoltorio estándar. Los casos más comunes aquí:

Relacionados

• Clientes (API pública)
• Instrumentos de pago
• Pedidos del Merchant