Metrics
Comparar períodos de métricas con la API
En POST /metrics/get-data envías el período principal y, si quieres, un período de comparación. La respuesta ya trae el valor actual y el anterior, así tu producto muestra la variación sin una segunda llamada. Sin OAuth, sin revisión de app, sin renovar tokens.
La llamada
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-08-01",
"end": "2026-08-31",
"comparison_start": "2026-07-01",
"comparison_end": "2026-07-31",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "fb_ads:spend",
"component": "number_v1",
"metrics": [
"spend"
]
}
]
}Qué puedes hacer
- Comparar el mes actual con el anterior, o cualquier par de períodos, en una sola llamada.
- Pedir varias métricas a la vez, cada una con su component.
- Ajustar la zona horaria con client_timezone para que los días cierren como espera tu cliente.
- Usar la versión asíncrona (get-data-async) con los mismos campos de comparación en períodos largos.
Reglas y límites
- comparison_start solo se considera si también se envía comparison_end.
- En el ejemplo de la spec, un number_v1 vuelve con value (período actual) y previous_value (período de comparación).
- El resultado viene en el objeto data, con el id (UUID) de cada métrica como clave.
- Si una métrica falla por separado, vuelve como objeto de error (por ejemplo no_data_in_period) y las demás vienen normalmente, con status 200.
- Cada llamada lee una conexión (customer_integration) y exige el x-customer-token del cliente.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| customer_integration | string | Sí | UUID de la conexión del cliente de donde se leen las métricas. Una por llamada. |
| start | string | Sí | Inicio del período (YYYY-MM-DD). Debe ser menor o igual a end. |
| end | string | Sí | Fin del período (YYYY-MM-DD). |
| comparison_start | string | No | Inicio del período de comparación (YYYY-MM-DD). Solo se considera si también se envía comparison_end. |
| comparison_end | string | No | Fin del período de comparación (YYYY-MM-DD). |
| client_timezone | string | No | Zona horaria, como America/Sao_Paulo (por defecto). |
| metrics | array | Sí | Lista de métricas pedidas, al menos una. Cada ítem trae id, reference_key, component y metrics. |
Para quién
Tarjetas de variación en dashboards
Tu panel muestra gasto o seguidores con la flecha de alza o caída sobre el período anterior, a partir de una sola respuesta.
Informes mensuales de agencia
Genera el comparativo mes a mes de cada cliente sin calcular la diferencia de tu lado.
Agentes que explican variaciones
Un agente lee actual y anterior y escribe el análisis de lo que cambió, con los números que vienen de la API.
Preguntas frecuentes
¿Cómo pido la comparación?
Envía comparison_start y comparison_end junto con start y end en POST /metrics/get-data. Si envías solo uno de los dos, la comparación no se considera.
¿El período de comparación debe tener el mismo tamaño?
La spec no lo exige: tú eliges las dos fechas. Para una comparación justa, usa períodos del mismo tamaño.
¿Funciona con todas las métricas?
Depende de la métrica y del component. El ejemplo de la spec muestra number_v1 volviendo con value y previous_value. Prueba la métrica que necesitas del catálogo GET /metrics/{integration_slug}.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
