Resumen del dashboard de la Organization
Consulta las estadísticas principales de la Organization — pedidos, tasas de aprobación y los Merchants principales entre todos los Merchants de la Organization.
Estos endpoints de solo lectura alimentan el dashboard inicial de la Organization: cifras agregadas de pedidos e ingresos, tendencias de tasa de aprobación y clasificaciones de los Merchants que generan más volumen.
Una Organization abarca todos los Merchants que contiene, por lo que estos números se consolidan entre todos ellos. Úsalos para una vista general; profundiza en un único Merchant a través del dashboard 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.
El objeto de estadísticas del dashboard
Devuelto por los endpoints de listado y consulta de esta página.
| Campo | Tipo | Descripción |
|---|---|---|
total_orders | number | Todos los pedidos en la ventana, incluidos los intentos rechazados. Este es el denominador de approval_rate y failure_rate. |
successful_orders | number | Pedidos que alcanzaron autorización — authorized, refunded, partially_refunded, charged_back y refund_pending. Excluye los intentos failed y canceled, y los pedidos aún en curso. |
approval_rate | number | Tasa de aprobación como porcentaje (0-100). |
failure_rate | number | Tasa de fallo como porcentaje (0-100). |
order_trend | array | Datos de tendencia de pedidos de los últimos 7 días. |
status_distribution | array | Distribución de pedidos por estado. |
top_merchants_by_orders | array | Merchants principales por número de pedidos. |
top_merchants_by_approval | array | Merchants principales por tasa de aprobación. |
Endpoints
GET/api/v1/org/dashboard/routing-overview
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Obtiene el resumen de enrutamiento en todos los Merchants 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. |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/dashboard/routing-overview \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"GET/api/v1/org/dashboard/stats
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Obtiene las estadísticas del dashboard de la Organization.
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
date_from | string | No | Fecha de inicio de las estadísticas (formato ISO 8601) |
date_to | string | No | Fecha de fin de las estadísticas (formato ISO 8601) |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/dashboard/stats \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string"Ejemplo de respuesta — 200
{
"total_orders": 42,
"successful_orders": 1,
"approval_rate": 92.4,
"failure_rate": 92.4,
"order_trend": [
{
"date": "string",
"count": 42
}
],
"status_distribution": [
{
"status": "active",
"count": 42,
"percentage": 92.4
}
],
"top_merchants_by_orders": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"order_count": 42
}
],
"top_merchants_by_approval": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"approval_rate": 92.4,
"total_orders": 42
}
]
}GET/api/v1/org/dashboard/top-merchants/by-approval-rate
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Merchants principales por tasa de aprobación de pedidos de la Organization.
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
date_from | string | No | Fecha de inicio (ISO 8601). Predeterminado: hace 30 días. |
date_to | string | No | Fecha de fin (ISO 8601). Predeterminado: ahora. |
limit | string | No | Cuántos Merchants devolver (predeterminado 5, máx. 50) |
min_orders | string | No | Número mínimo de pedidos para inclusión (predeterminado 10) |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/dashboard/top-merchants/by-approval-rate \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string" \
--data-urlencode "limit=string" \
--data-urlencode "min_orders=string"Ejemplo de respuesta — 200
{
"data": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"approval_rate": 92.4,
"total_orders": 42
}
]
}GET/api/v1/org/dashboard/top-merchants/by-orders
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Merchants principales por número total de pedidos de la Organization.
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
date_from | string | No | Fecha de inicio (ISO 8601). Predeterminado: hace 30 días. |
date_to | string | No | Fecha de fin (ISO 8601). Predeterminado: ahora. |
limit | string | No | Cuántos Merchants devolver (predeterminado 5, máx. 50) |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/dashboard/top-merchants/by-orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string" \
--data-urlencode "limit=string"Ejemplo de respuesta — 200
{
"data": [
{
"merchant_id": "mrc_8a3f12d9",
"merchant_name": "Acme Store",
"order_count": 42
}
]
}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. |