Clientes de la Organization
Explora los clientes de todos los Merchants de la Organization desde el Dashboard.
Estos endpoints le dan a la Organization una vista consolidada de los clientes en todos sus Merchants: buscar, listar y abrir un registro para ver el detalle.
Los clientes nunca cruzan los límites de un Merchant — la misma persona en dos Merchants son dos registros — por lo que esta vista agrega en lugar de fusionar. Úsala para responder preguntas a nivel de toda la Organization; gestiona un cliente en su propia pantalla de clientes del Merchant.
Estos endpoints impulsan la interfaz del Tokeflow Dashboard a nivel de la Organization. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-organization-id, y el usuario que inició sesión debe ser miembro de esa Organization.
Endpoints
GET/api/v1/org/customers
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Lista los clientes de la Organization.
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mín. 1. |
limit | number | No | Número de elementos por página. Predeterminado 20, mín. 1, máx. 100. |
merchant_id | string | No | Filtra por ID de Merchant |
search | string | No | Busca por nombre, correo electrónico o ID de cliente |
start_date | string | No | Fecha de inicio (ISO 8601) |
end_date | string | No | Fecha de fin (ISO 8601) |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/customers \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "merchant_id=mrc_8a3f12d9" \
--data-urlencode "search=string"GET/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Obtiene un cliente por ID.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"PATCH/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Actualiza un cliente.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | No | — |
email | string | No | — |
phone | string | No | — |
document_type | string | No | Uno de cpf, cnpj, passport, tax_id. |
document_number | string | No | — |
Ejemplo de solicitud
curl -X PATCH https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Store",
"email": "jane@example.com",
"phone": "+5511987654321",
"document_type": "cpf",
"document_number": "12345678909"
}'Errores
Los errores usan el envoltorio estándar. Los casos más comunes aquí:
| HTTP | Significado |
|---|---|
400 | Parámetros inválidos o un estado que no permite esta operación. |
401 | Token de sesión del Dashboard ausente, expirado o inválido. |
403 | Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad. |
404 | El registro no existe o no es visible para esta entidad. |