05 · API

Lee tus cifras con la API REST

Las mismas cifras del panel, en JSON, para un sitio, con una clave que solo puede leer.

01Claves

Crea claves en la página Setup del sitio, en API keys. Una clave (opa_ y 40 caracteres) se muestra una sola vez: solo se guardan un hash de ella y sus primeros caracteres.
Una clave lee un solo sitio, aquel en el que se creó. Revocarla surte efecto al instante.
Una clave solo lee, salvo que se marcara Record payments al crearla: entonces también puede enviar pagos (Payments API).

Envía la clave en cada solicitud como Authorization: Bearer opa_…:

Shell

export TALLY_API_KEY=opa_…
curl -s -H "Authorization: Bearer $TALLY_API_KEY" "https://tallybyoutpost.com/api/v1/sites"

02Rutas

Todas son GET, bajo https://tallybyoutpost.com/api/v1, y {id} es el ID del sitio. Cada una acepta los parámetros del panel y devuelve las mismas cifras que el panel:

Ruta	Qué devuelve
`GET /sites`	El sitio de la clave: su ID, nombre, dominio, zona horaria y modo.
`GET /sites/{id}/overview`	Las cifras del panel para un periodo y el anterior: visitantes, vistas de página, visitas, tiempo activo e ingresos.
`GET /sites/{id}/timeseries`	El gráfico: visitantes y vistas de página por hora o por día, con los ingresos cuando hay pagos.
`GET /sites/{id}/breakdown/{dimension}`	Fuentes, canales, páginas, países, dispositivos y el resto, con los ingresos de cada fila.
`GET /sites/{id}/sales`	Pagos, del más reciente al más antiguo, cada uno con cómo se vinculó.
`GET /sites/{id}/receipts/{payment_id}`	El comprobante de un pago: la cadena desde la primera visita hasta el pago.
`GET /sites/{id}/coverage`	La proporción de ventas vinculadas a un visitante, por método, y los arreglos.
`GET /sites/{id}/visitors`	La lista de visitantes, con las visitas de cada uno y lo que pagó.
`GET /sites/{id}/visitors/{visitor}`	El recorrido de un visitante.
`GET /sites/{id}/goals`	Cada objetivo completado, con sus visitantes que convierten y sus ingresos, y los embudos.
`GET /sites/{id}/funnels/{id}`	Un embudo, paso a paso.
`GET /sites/{id}/realtime`	Quién está en el sitio en los últimos cinco minutos, y las ventas de la última hora.
`GET /sites/{id}/peak-hours`	Visitas, ventas e ingresos por día de la semana y hora local.
`GET /sites/{id}/pages`	Cómo se leen las páginas: vistas, tiempo de lectura, profundidad de scroll, entradas y salidas.
`GET /sites/{id}/path-to-purchase`	Cómo llegaron los compradores: tiempo y visitas antes de pagar, y de la fuente del primer contacto a la fuente atribuida.
`GET /sites/{id}/ltv`	Valor de vida del cliente según la fuente que trajo primero a cada cliente.

Fuentes por ingresos, últimos 30 días

curl -s -H "Authorization: Bearer $TALLY_API_KEY" \
  "https://tallybyoutpost.com/api/v1/sites/k3xq2mfa7twp/breakdown/source?period=30d&sort=revenue"

03Parámetros

Parámetro	Valores
`period`	`today`, `yesterday`, `7d`, `30d`, `12m`. Cada ruta tiene un valor predeterminado.
`from`, `to`	Un rango personalizado, `YYYY-MM-DD`, con los dos extremos indicados, de hasta 366 días. No se combina con `period`.
`compare`	`off` (el predeterminado), `previous` o `year`.
`f.<dim>`	Un filtro: `f.country=DE`, `f.source=x.com`, `f.page=/pricing`, `f.device=mobile` y las demás dimensiones del panel.
`limit`, `cursor`	Filas por página, y el `next_cursor` de la página anterior.

Un parámetro que una ruta no acepta se rechaza con 400, así que una errata nunca se hace pasar por una respuesta.

04Respuestas

JSON, con el dinero en centavos enteros y su moneda: {"cents": 4900, "currency": "USD", "exponent": 2}. Los totales están en dólares estadounidenses; cada venta lleva también su importe tal como se cobró.
Las fechas y horas van en RFC 3339 y en UTC; los días se cortan en la zona horaria del sitio, que indica cada range.
Las proporciones y tasas van de 0 a 1: 0.1234 es el 12,34 %.
Los errores son {"error": {"code", "message"}}, donde el mensaje es una frase que puedes mostrar tal cual: 400 invalid_parameter, 401 unauthorized, 402 payment_required (la cuenta no tiene plan), 404 not_found, 429 rate_limited y 503 unavailable.

05Límites de solicitudes

Cada clave puede hacer 120 solicitudes por minuto, sumando REST y MCP, y el cupo se recarga sobre la marcha. Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining; pasado el límite, 429 con Retry-After en segundos.

06Comprueba que funciona

¿Falta algo o no coincide con lo que ves? Escribe a support@tallybyoutpost.com y dinos qué página.