Resumen del dashboard del Merchant
El endpoint de estadísticas detrás de la pantalla de inicio del dashboard del merchant — volúmenes de pedidos, tasas de aprobación y fallo, datos de tendencia y pedidos recientes para una ventana de fechas.
La pantalla de inicio del dashboard del Merchant funciona con un único endpoint de estadísticas. Dada una ventana de fechas, devuelve los números agregados que el dashboard renderiza como bloques destacados (total de pedidos, tasa de aprobación, tasa de fallo), además de los conjuntos de datos detrás de sus gráficos: una serie de tendencia de pedidos, un desglose de distribución por estado y los pedidos más recientes.
Todas las cifras se calculan sobre pedidos — el registro comercial que agrupa uno o más intentos de cobro — no sobre transacciones individuales. Un pedido que falló en el primer proveedor y tuvo éxito en un proveedor de respaldo cuenta una sola vez, como un pedido exitoso. Consulta Pedidos para saber cómo se relacionan los pedidos con las transacciones.
Los endpoints del Dashboard alimentan la Tokeflow Dashboard UI. Están autenticados por sesión: inicia sesión para obtener un JWT y envíalo como token bearer. No aceptan claves de API sk_ o pk_ — para informes programáticos, usa la API pública.
El objeto de estadísticas
La respuesta es un único objeto de estadísticas (sin envoltorio):
| 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 | Pedidos autorizados / total, como porcentaje con 1 decimal. |
failure_rate | number | Pedidos fallidos / total, como porcentaje con 1 decimal. |
success_rate | number | Alias de approval_rate, mantenido por compatibilidad con clientes. Siempre es igual a approval_rate. |
order_trend | array | Serie temporal de la actividad de pedidos a lo largo de la ventana — un OrderTrendPointDto por punto. Alimenta el gráfico de tendencia del dashboard. |
status_distribution | array | Desglose de los pedidos por estado — un StatusDistributionItemDto por grupo de estado. Alimenta el gráfico de distribución del dashboard. |
recent_orders | array | Los pedidos más recientes en la ventana — un RecentOrderDto por pedido. Alimenta la lista de actividad reciente del dashboard. |
Los ocho campos siempre están presentes en la respuesta.
Un pedido cuenta como exitoso en cuanto alcanza autorización, incluso si más adelante se reembolsa o se disputa (contracargo) — los pedidos refunded, partially_refunded y charged_back fueron cargos aprobados de todos modos. approval_rate y failure_rate no necesariamente suman 100: los pedidos cancelados o aún en curso no pertenecen a ninguno de los dos grupos.
Endpoints
GET/api/v1/merchant/dashboard/stats
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Devuelve las estadísticas del dashboard del Merchant para la ventana de fechas solicitada.
Parámetros de encabezado
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
x-merchant-id | string | Sí | El Merchant sobre el que se informa, prefijado con mrc_. Selecciona el contexto de Merchant activo cuando tu cuenta pertenece a más de un Merchant. |
Parámetros de consulta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
date_from | string | Sí | Inicio de la ventana de informe (timestamp ISO 8601, inclusivo). |
date_to | string | Sí | Fin de la ventana de informe (timestamp ISO 8601, inclusivo). |
La interfaz del dashboard solicita ajustes preestablecidos comunes — últimos 7 días, últimos 30 días, mes en curso. Al llamar tú mismo al endpoint, mantén la ventana lo más acotada posible para tu caso de uso; los agregados se calculan sobre todos los pedidos del rango.
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/merchant/dashboard/stats \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
-H "x-merchant-id: mrc_123" \
--data-urlencode "date_from=2026-07-01T00:00:00Z" \
--data-urlencode "date_to=2026-07-31T23:59:59Z"Ejemplo de respuesta — 200 OK
{
"total_orders": 59,
"successful_orders": 42,
"approval_rate": 71.2,
"failure_rate": 8.5,
"success_rate": 71.2,
"order_trend": [],
"status_distribution": [],
"recent_orders": []
}Los tres arrays se muestran vacíos arriba por brevedad. En una respuesta real, order_trend trae un punto por intervalo dentro de la ventana, status_distribution trae un grupo por cada estado de pedido presente en la ventana, y recent_orders trae los pedidos más recientes — cada elemento sigue, respectivamente, los formatos OrderTrendPointDto, StatusDistributionItemDto y RecentOrderDto.
En este ejemplo, 42 de 59 pedidos alcanzaron autorización (42 / 59 = 71.2%) y 5 fallaron por completo (5 / 59 = 8.5%); los pedidos restantes fueron cancelados o aún estaban en curso, por lo que no cuentan para ninguna de las dos tasas.
Errores
| HTTP | Causa típica |
|---|---|
400 | date_from / date_to ausente o inválido. |
401 | Token de sesión ausente, inválido o expirado — inicia sesión de nuevo. |
403 | La cuenta de la sesión no es miembro del Merchant indicado en x-merchant-id. |
Consulta Errores para conocer el formato de error usado en toda la API.
Relacionados
- Pedidos — el recurso que agregan estas estadísticas.
- Transacciones — los intentos de cobro individuales detrás de cada pedido.
- Organizations y Merchants — cómo funciona la membresía de Merchant.
- Invitaciones del Dashboard — invita a compañeros de equipo al dashboard.