Estadísticas

Las métricas del programa: ingresos, retorno y valor por cliente, y cómo consultarlas

La API expone tres endpoints de estadísticas agregadas. Sirven para responder preguntas de negocio —cuánto generó el programa, cuál fue el retorno, qué premios se canjean, qué campaña trajo clientes— sin tener que traer el historial completo y sumarlo vos.

Los tres son de sólo lectura y los tres aceptan el mismo par de filtros de fecha.

Endpoint	Qué devuelve
`GET /api/v2/statistics/revenue`	Ingresos, costo, ROI y LTV de la cuenta, con series por día
`GET /api/v2/templates/{templateId}/statistics/rewards`	Estadísticas por premio de una plantilla
`GET /api/v2/templates/{templateId}/statistics/utm`	Estadísticas por enlace UTM de una plantilla

Base URL https://api.dardo.ai, autenticación con el header X-API-Key — ver Autenticación. El detalle operación por operación de cada uno está en la referencia de Estadísticas.

`GET /api/v2/statistics/revenue`

El endpoint principal, y el único de los tres cuya respuesta está completamente declarada en el spec. Devuelve las métricas económicas del programa para el recorte que le pidas.

curl "https://api.dardo.ai/api/v2/statistics/revenue?startDate=2026-08-01&endDate=2026-08-31" \
  -H "X-API-Key: TU_CLAVE_API"

Parámetros

Los cuatro son de query string y los cuatro son opcionales.

Parámetro	Tipo	Default	Para qué
`companyId`	integer	—	Acota a una cuenta puntual. Útil si tu clave alcanza más de una
`templateId`	integer	—	Acota a una plantilla de tarjeta
`startDate`	string, formato `Y-m-d`	`null`	Desde cuándo
`endDate`	string, formato `Y-m-d`	`null`	Hasta cuándo

Este endpoint no se pagina: devuelve un objeto único, no una lista. No acepta page ni itemsPerPage.

Los campos de la respuesta

data es un objeto con seis campos. Los seis son obligatorios: siempre vienen.

Campo	Tipo	Qué mide, en términos de negocio
`totalCost`	number	Lo que costó el programa en el período: el lado de la inversión de la ecuación
`revenueTotal`	number	Lo que el programa generó en el período: el lado del retorno
`revenueByDay`	array	La misma facturación, abierta día por día. Es la serie que graficás
`roi`	number	La relación entre lo generado y lo invertido, para todo el período
`roiByDay`	array	El ROI abierto día por día
`ltv`	number	El valor promedio por cliente a lo largo de su vida en el programa

totalCost y revenueTotal son el par que importa: uno solo no dice nada. Un programa que generó mucho habiendo costado más no es un buen programa, y roi existe justamente para no tener que hacer esa cuenta a mano. ltv es la métrica de horizonte largo: cuánto vale, en promedio, un cliente que entra al programa — la que usás para decidir cuánto podés gastar en conseguir uno nuevo.

La forma de las series por día

Cada elemento de revenueByDay y de roiByDay es un objeto de exactamente dos campos, los dos obligatorios:

Campo	Tipo	Qué es
`date`	string	El día del punto de la serie
`value`	number	El valor de la métrica para ese día

Es decir, revenueByDay y roiByDay comparten la misma estructura. Un solo componente de gráfico te sirve para las dos.

Respuesta completa

{
  "responseId": "9f8b1c2d-4a3e-4b71-9c02-1d5e7f8a9b40",
  "createdAt": "2026-09-01T14:32:07+00:00",
  "code": 200,
  "data": {
    "totalCost": 48200.0,
    "revenueTotal": 214750.0,
    "revenueByDay": [
      { "date": "2026-08-01", "value": 6120.0 },
      { "date": "2026-08-02", "value": 7340.5 }
    ],
    "roi": 3.45,
    "roiByDay": [
      { "date": "2026-08-01", "value": 3.1 },
      { "date": "2026-08-02", "value": 3.6 }
    ],
    "ltv": 18930.0
  }
}

Lo que el spec no declara de estas métricas

Los tipos están, las definiciones de cálculo no. Antes de montar un reporte contable sobre estos números, confirmá estos puntos con soporte@dardo.ai:

La unidad de totalCost, revenueTotal y ltv. Son números sin moneda declarada y la respuesta no trae un campo de moneda. En otras partes de la API la unidad sí está explicitada y no siempre es la misma —purchaseSum va en unidades de la moneda de la cuenta y los montos de Punto de venta van en centavos—, así que no lo des por supuesto.
La escala de roi. Si 3.45 es un múltiplo o un porcentaje cambia por completo lo que mostrás en pantalla.
Qué entra en totalCost y sobre qué ventana se calcula ltv: si ltv respeta el rango de fechas del pedido o es un valor histórico.
El formato exacto de date en las series: el spec lo declara como string a secas, sin format, a diferencia de startDate y endDate.
Los días sin actividad: si aparecen con value: 0 o si se omiten. De eso depende si tenés que rellenar los huecos antes de graficar.

`GET /api/v2/templates/{templateId}/statistics/rewards`

Estadísticas por premio de una plantilla: la vista de qué se está canjeando.

`GET /api/v2/templates/{templateId}/statistics/utm`

Estadísticas por enlace UTM de una plantilla: qué campaña de adquisición trajo tarjetas. Los enlaces en sí los listás con GET /api/v2/templates/{templateId}/utm-links.

Parámetros de los dos

Parámetro	Ubicación	Tipo	Requerido
`templateId`	path	string	Sí
`startDate`	query	string, formato `Y-m-d`	No
`endDate`	query	string, formato `Y-m-d`	No

En estos dos endpoints el spec declara templateId como string, mientras que el mismo templateId como filtro en /statistics/revenue y en /operations está declarado como integer. En la URL se serializa igual y no cambia nada en la práctica, pero si generás un cliente tipado desde el spec te van a salir dos tipos distintos para el mismo dato.

La forma de estas dos respuestas todavía no está publicada

Los dos endpoints devuelven un array dentro del sobre estándar, pero el spec define el objeto de cada fila como {"type": "object"} vacío: sin propiedades, sin campos requeridos, sin ejemplo.

Traducido: sabemos que devuelven una lista, no sabemos qué campos trae cada elemento. No inventamos acá una tabla de campos que después no coincida con lo que te llega.

Lo práctico es hacer una llamada de prueba contra una plantilla tuya y mirar la respuesta real antes de escribir el parser. Si necesitás el contrato por escrito para tipar un cliente, pedilo a soporte@dardo.ai.

# Premios canjeados de la plantilla 123, en agosto
curl "https://api.dardo.ai/api/v2/templates/123/statistics/rewards?startDate=2026-08-01&endDate=2026-08-31" \
  -H "X-API-Key: TU_CLAVE_API"

# Rendimiento de los enlaces UTM de la misma plantilla
curl "https://api.dardo.ai/api/v2/templates/123/statistics/utm?startDate=2026-08-01&endDate=2026-08-31" \
  -H "X-API-Key: TU_CLAVE_API"

Los filtros de fecha

Los tres endpoints comparten la misma definición de startDate y endDate. Lo que el spec declara es esto:

Propiedad	Valor
Ubicación	query string
Tipo	`string`, formato `date`
Formato documentado	`Y-m-d`, o sea `YYYY-MM-DD`. Ejemplo: `2026-08-31`
Default	`null`
Requerido	No

Son fechas sin hora: no se puede acotar a un rango horario dentro del día con estos parámetros.

Lo que no podemos afirmar sobre el rango

El spec declara el formato y nada más. Estas cuatro cosas no están documentadas y conviene confirmarlas con soporte@dardo.ai antes de cerrar un reporte:

Pregunta	Por qué importa
¿Los extremos son inclusivos?	Si `endDate=2026-08-31` incluye o no ese día, cambia el total del mes
¿En qué zona horaria se interpretan?	Si el corte se hace en UTC y tu negocio está en otro huso, las primeras horas de cada día caen del lado equivocado y todos los cortes diarios quedan movidos
¿Hay un rango máximo?	Si pedir varios años de una sola vez funciona, tarda o falla
¿Qué pasa si los omitís?	El default es `null`. Lo esperable es "todo el histórico", pero el spec no lo dice y podría haber una ventana implícita del lado del servidor

Mientras no estén confirmadas, la forma segura de conciliar es mandar siempre startDate y endDate explícitos sobre un período ya cerrado, y contrastar el total contra Operaciones y eventos.

Qué no cubren estas métricas

Las estadísticas son agregados. No traen ni una sola transacción individual: no hay fecha y hora de cada movimiento, ni qué cliente lo hizo, ni en qué sucursal, ni por qué canal entró.

Todo eso está en Operaciones y eventos, que devuelve el historial fila por fila y trae purchaseSum —el monto de la compra asociada— en cada operación.

Necesitás	Usá
El número que va en el tablero: ingresos, ROI, LTV, la serie diaria	Estadísticas
Comparar períodos o plantillas de un vistazo	Estadísticas
Auditar de dónde sale un total, transacción por transacción	Operaciones y eventos
Conciliar contra tu sistema de facturación	Operaciones y eventos, sumando `purchaseSum`
Saber qué cliente, qué sucursal, qué canal	Operaciones y eventos

La regla es simple: estadísticas para el agregado, operaciones para el detalle y la conciliación. Y si un total no cierra, la fuente de verdad para investigarlo es siempre el historial de operaciones, porque es el único que te deja ver las filas que lo componen.

Estadísticas

On this page