# Referencia de la API pública (REST, /v1)

URL: https://traqio.app/es/docs/api
Last updated: 2026-10-14

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](https://traqio.app/es/docs/api/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.

```bash
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](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-DD` en UTC. `from` es inclusivo y `to` es **exclusivo**: `from=2026-09-01&to=2026-10-01` es septiembre.
- Las rutas de informes aceptan `productId`, `from` y `to`; `store=ios|android` es 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-spend` se 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

```bash
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](https://traqio.app/es/docs/concepts/tracking-links) 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.