API
Referencia de la API pública (REST, /v1)
Consulta ROAS, cohortes, ingresos y enlaces de seguimiento desde tu código con la API REST versionada de Traqio: una clave de API con scopes, OpenAPI, curl.
La API pública de Traqio es una API REST versionada, bajo /v1, sobre los mismos informes que la consola: ROAS por campaña, conjunto de anuncios y anuncio, ROAS diario, cohortes de instalaciones, ingresos, datos rechazados, estado de los conectores y enlaces de seguimiento. Las mismas operaciones están disponibles como herramientas para Claude, Cursor y otros clientes MCP a través del servidor MCP. Ambos se autentican con una única clave de API con scopes.
Autenticación#
Crea una clave en la consola en Ajustes → Claves de API, marca sus scopes y envíala como token bearer. Las claves empiezan por tq_live_ y se muestran una sola vez — Traqio solo guarda un hash y el prefijo visible de la clave. La API rechaza un token de sesión de la consola, y la consola rechaza una clave de API.
export TRAQIO_API_KEY=tq_live_…
# 1. Which apps do I have? Every report takes a productId.
curl -s "https://api.traqio.app/v1/products" -H "Authorization: Bearer $TRAQIO_API_KEY"
# 2. Which ads made money in September? (`to` is exclusive)
curl -s -G "https://api.traqio.app/v1/reports/roas" -H "Authorization: Bearer $TRAQIO_API_KEY" \
-d productId=app_… -d from=2026-09-01 -d to=2026-10-01 -d level=ad
# 3. Is the spend pull healthy, or is every ROAS stale?
curl -s "https://api.traqio.app/v1/reports/connectors" -H "Authorization: Bearer $TRAQIO_API_KEY"Scopes#
| Scope | Permite |
|---|---|
reports:read | GET /v1/products y todas las rutas GET /v1/reports, y las herramientas MCP correspondientes. |
reports:write | POST /v1/reports/sync-spend — lanzar una obtención de la inversión o un relleno histórico. |
links:read | Listar los enlaces de seguimiento de una app. |
links:write | Crear enlaces de seguimiento. |
privacy:write | Borrar los datos de un usuario (RGPD) — irreversible. Solo owners y admins pueden concederlo. |
Ningún scope implica otro — links:write no concede links:read — y una clave nunca puede hacer más que el rol del miembro que la creó. Revocar una clave surte efecto en su siguiente llamada.
Endpoints#
| Método | Ruta | Scope | Parámetros | Devuelve |
|---|---|---|---|---|
| GET | /v1/products | reports:read | — | Tus apps: id, nombre, ids de tienda. Nunca las claves SDK. |
| GET | /v1/reports/roas | reports:read | productId, from, to, store?, level? | ROAS por campaña, conjunto de anuncios o anuncio (level=campaign|adset|ad): inversión, ingresos atribuidos, instalaciones. |
| GET | /v1/reports/roas-daily | reports:read | productId, from, to, store? | Inversión, ingresos y ROAS por día. |
| GET | /v1/reports/cohorts | reports:read | productId, from, to, store? | Cohortes por día de instalación: instalaciones, ingresos del día 0, ingresos totales. |
| GET | /v1/reports/revenue | reports:read | productId, from, to | Todos los ingresos por moneda, separados en atribuidos, orgánicos y no asociados. |
| GET | /v1/reports/rejections | reports:read | productId, from, to | Lo que Traqio rechazó — límite de frecuencia, reglas antifraude — por motivo y por ruta. |
| GET | /v1/reports/connectors | reports:read | — | Tus conexiones con redes publicitarias, con su última sincronización y su último error. |
| POST | /v1/reports/sync-spend | reports:write | date | from, to | Obtener ahora la inversión de un día (date=) o de un rango (from=, to=). Se puede llamar dos veces sin riesgo. |
| GET | /v1/links | links:read | productId | Los enlaces de seguimiento de una app, los más recientes primero (200 como máximo). |
| POST | /v1/links | links:write | { … } (JSON) | Crear un enlace de seguimiento; devuelve su URL. |
| POST | /v1/privacy/erasure | privacy:write | { productId, deviceId?, appUserId?, confirm: true } (JSON) | Borrar todo lo relativo a un id de dispositivo y/o de usuario en una app; devuelve el recibo del borrado. Irreversible. |
La referencia completa legible por máquina está disponible sin autenticación en https://api.traqio.app/v1/openapi.json (OpenAPI 3.1). Se genera a partir de la misma descripción con la que se prueban las rutas, así que no puede describir un endpoint que no existe.
Convenciones#
- Las fechas están en formato
YYYY-MM-DDen UTC.fromes inclusivo ytoes exclusivo:from=2026-09-01&to=2026-10-01es septiembre. - Las rutas de informes aceptan
productId,fromyto;store=ios|androides opcional y, sin él, se combinan ambas tiendas. - El dinero nunca se suma entre monedas: cada moneda es su propia fila, y la inversión está en la moneda de facturación de cada cuenta publicitaria.
POST /v1/reports/sync-spendse puede llamar dos veces sin riesgo: un día se sobrescribe, nunca se duplica — que es también como se recogen las correcciones que una red hace sobre la inversión reciente.
Crear un enlace de seguimiento#
curl -s -X POST "https://api.traqio.app/v1/links" \
-H "Authorization: Bearer $TRAQIO_API_KEY" -H "content-type: application/json" \
-d '{
"productId": "app_…",
"label": "Meta / autumn / video B",
"network": "meta",
"campaignExtId": "1203…",
"code": "autumn-b",
"deepLink": "/offers/autumn"
}'| Campo | Significado |
|---|---|
productId | La app a la que apunta el enlace, obtenida de GET /v1/products. |
label? | Tu nombre para el enlace, p. ej. «Meta / verano / video-A». |
network? | meta, tiktok u other. |
source? | Canal en texto libre, cuando la red es other. |
campaignExtId? | El id de campaña propio de la red — lo que une el enlace con la inversión. |
adsetExtId? | El id del conjunto de anuncios propio de la red. |
adExtId? | El id de anuncio propio de la red. |
code? | El slug, /c/<code>: de 1 a 50 caracteres entre A–Z a–z 0–9 - _. Aleatorio si se omite; 409 si ya está ocupado. |
deepLink? | Dónde aterriza la app: una ruta interna o una URL de app. Se rechazan javascript:, data: y similares. |
iosUrl? | Destino iOS personalizado, solo https. Por defecto, la página de la app en el App Store. |
androidUrl? | Destino Android personalizado, solo https. Por defecto, la ficha de Play. |
webUrl? | Una página de tu sitio, solo https. Si se indica, todos los dispositivos llegan ahí con el trackID (traq_click) en la URL. |
Consulta Enlaces de seguimiento para saber qué hace cada campo una vez publicado el enlace.
Errores#
| Estado | Significa |
|---|---|
| 400 | Petición mal formada: una fecha que no se puede interpretar, un productId que falta, un level que no es campaign, adset ni ad. |
| 401 | Sin clave, una clave mal formada, revocada o caducada, o un token de sesión de la consola. El mensaje indica cuál. |
| 403 | A la clave le falta el scope (el mensaje lo nombra), o el productId pertenece a otro espacio de trabajo. |
| 409 | POST /v1/links: el slug ya está ocupado. |
Los errores son JSON, con un message legible por humanos.
Preguntas frecuentes#
- ¿La API está incluida en todos los planes?
- Sí. La API y el servidor MCP no dependen del plan: todas las cuentas pueden crear claves de API.
- ¿Puede una clave de API crear otras claves o cambiar la facturación?
- No. Una clave lee informes y, con los scopes de escritura correspondientes, lanza una obtención de la inversión, crea enlaces de seguimiento o borra los datos de un usuario a petición. Gestionar claves, credenciales, miembros o la facturación siempre requiere una persona con la sesión iniciada.
- ¿Qué pasa con una clave cuando su creador deja el equipo?
- Nada: una clave pertenece al espacio de trabajo, no a la persona que la creó, así que una integración no se rompe cuando esa persona se va. Revoca desde la consola las claves que ya no quieras; cada una muestra cuándo se usó por última vez, y una clave revocada se rechaza en su siguiente llamada.
- ¿Cambiará la API bajo mi integración?
- No dentro de /v1. Los cambios aditivos — un endpoint nuevo, un campo nuevo en una respuesta — se hacen dentro de /v1; todo lo que pudiera romper una integración que funciona pasa a /v2, y /v1 sigue respondiendo.