# Référence de l’API publique (REST, /v1)

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

ROAS, cohortes, revenus et liens de tracking depuis votre code, via l’API REST versionnée de Traqio : une clé API à scopes, OpenAPI, des exemples curl.

L’**API publique** de Traqio est une API REST versionnée, sous `/v1`, qui expose les mêmes rapports que la console : ROAS par campagne, ensemble de publicités et publicité, ROAS quotidien, cohortes d’installations, revenus, données refusées, état des connecteurs et liens de tracking. Les mêmes opérations sont disponibles comme outils pour Claude, Cursor et d’autres clients MCP via le [serveur MCP](https://traqio.app/fr/docs/api/mcp). Les deux s’authentifient avec une seule clé API à scopes.

## Authentification

Créez une clé dans la console sous **Paramètres → Clés d’API**, cochez ses scopes, et envoyez-la comme jeton bearer. Les clés commencent par `tq_live_` et ne sont affichées qu’une fois — Traqio ne stocke qu’un hachage et le préfixe visible de la clé. Un jeton de connexion à la console est refusé par l’API, et une clé API est refusée par la console.

```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 | Autorise |
| --- | --- |
| reports:read | GET /v1/products et toutes les routes GET /v1/reports, ainsi que les outils MCP correspondants. |
| reports:write | POST /v1/reports/sync-spend — déclencher une récupération des dépenses ou un backfill. |
| links:read | Lister les liens de tracking d’une app. |
| links:write | Créer des liens de tracking. |
| privacy:write | Effacer les données d’un utilisateur (RGPD) — irréversible. Seuls les owners et admins peuvent l’accorder. |

Aucun scope n’en implique un autre — `links:write` n’accorde pas `links:read` — et une clé ne peut jamais faire plus que ce que permet le rôle du membre qui l’a créée. La révocation d’une clé prend effet à son appel suivant.

## Endpoints

| Méthode | Chemin | Scope | Paramètres | Renvoie |
| --- | --- | --- | --- | --- |
| GET | /v1/products | reports:read | — | Vos apps : id, nom, identifiants de store. Jamais les clés SDK. |
| GET | /v1/reports/roas | reports:read | productId, from, to, store?, level? | ROAS par campagne, ensemble de publicités ou publicité (level=campaign|adset|ad) : dépenses, revenus attribués, installations. |
| GET | /v1/reports/roas-daily | reports:read | productId, from, to, store? | Dépenses, revenus et ROAS par jour. |
| GET | /v1/reports/cohorts | reports:read | productId, from, to, store? | Cohortes par jour d’installation : installations, revenus au jour 0, revenus totaux. |
| GET | /v1/reports/revenue | reports:read | productId, from, to | Tous les revenus par devise, répartis entre attribués, organiques et non rapprochés. |
| GET | /v1/reports/rejections | reports:read | productId, from, to | Ce que Traqio a refusé — plafond de débit, règles antifraude — par motif et par route. |
| GET | /v1/reports/connectors | reports:read | — | Vos connexions aux réseaux publicitaires, avec leur dernière synchronisation et leur dernière erreur. |
| POST | /v1/reports/sync-spend | reports:write | date | from, to | Récupérer les dépenses maintenant pour un jour (date=) ou une période (from=, to=). Sans risque si appelé deux fois. |
| GET | /v1/links | links:read | productId | Les liens de tracking d’une app, du plus récent au plus ancien (200 au maximum). |
| POST | /v1/links | links:write | { … } (JSON) | Créer un lien de tracking ; renvoie son URL. |
| POST | /v1/privacy/erasure | privacy:write | { productId, deviceId?, appUserId?, confirm: true } (JSON) | Effacer tout ce qui concerne un identifiant d’appareil et/ou d’utilisateur dans une app ; renvoie le reçu d’effacement. Irréversible. |

La référence complète, lisible par machine, est accessible sans authentification à [https://api.traqio.app/v1/openapi.json](https://api.traqio.app/v1/openapi.json) (OpenAPI 3.1). Elle est générée à partir de la même description que celle contre laquelle les routes sont testées : elle ne peut donc pas décrire un endpoint qui n’existe pas.

## Conventions

- Les **dates** sont au format `YYYY-MM-DD` en UTC. `from` est inclus et `to` est **exclu** : `from=2026-09-01&to=2026-10-01` correspond à septembre.
- Les routes de rapport prennent `productId`, `from` et `to` ; `store=ios|android` est optionnel, et les deux stores sont combinés sans lui.
- L’**argent** n’est jamais additionné entre devises : chaque devise a sa propre ligne, et les dépenses sont dans la devise de facturation de chaque compte publicitaire.
- `POST /v1/reports/sync-spend` peut être appelé deux fois sans risque : un jour est écrasé, jamais doublé — c’est aussi ainsi que les corrections d’un réseau sur ses dépenses récentes sont intégrées.

## Créer un lien de tracking

```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"
  }'
```

| Champ | Signification |
| --- | --- |
| productId | L’app vers laquelle pointe le lien, issue de GET /v1/products. |
| label? | Le nom que vous lui donnez, par ex. « Meta / été / vidéo-A ». |
| network? | meta, tiktok ou other. |
| source? | Canal en texte libre, quand le réseau est other. |
| campaignExtId? | L’identifiant de campagne propre au réseau — ce qui relie le lien aux dépenses. |
| adsetExtId? | L’identifiant d’ensemble de publicités propre au réseau. |
| adExtId? | L’identifiant de publicité propre au réseau. |
| code? | Le slug, /c/<code> : 1 à 50 caractères parmi A–Z a–z 0–9 - _. Aléatoire s’il est omis ; 409 s’il est déjà pris. |
| deepLink? | Où l’app s’ouvre : un chemin dans l’app ou une URL d’app. javascript:, data: et similaires sont refusés. |
| iosUrl? | Destination iOS personnalisée, https uniquement. Par défaut, la page App Store de l’app. |
| androidUrl? | Destination Android personnalisée, https uniquement. Par défaut, la fiche Play. |
| webUrl? | Une page de votre site, https uniquement. Si elle est renseignée, tous les appareils y arrivent avec le trackID (traq_click) dans l’URL. |

Voir [Liens de tracking](https://traqio.app/fr/docs/concepts/tracking-links) pour ce que fait chaque champ une fois le lien en ligne.

## Erreurs

| Statut | Signification |
| --- | --- |
| 400 | Requête mal formée : une date illisible, un productId manquant, un level qui n’est ni campaign, ni adset, ni ad. |
| 401 | Pas de clé, une clé mal formée, révoquée ou expirée, ou un jeton de connexion à la console. Le message précise lequel. |
| 403 | La clé n’a pas le scope requis (le message le nomme), ou l’productId appartient à un autre espace de travail. |
| 409 | POST /v1/links : le slug est déjà pris. |

Les erreurs sont en JSON, avec un `message` lisible par un humain.

## Questions fréquentes

**L’API est-elle incluse dans chaque offre ?**
Oui. L’API et le serveur MCP ne dépendent pas de l’offre : chaque compte peut créer des clés API.

**Une clé API peut-elle créer d’autres clés ou modifier la facturation ?**
Non. Une clé lit les rapports et, avec les scopes d’écriture correspondants, déclenche une récupération des dépenses, crée des liens de tracking ou efface les données d’un utilisateur sur demande. Gérer les clés, les identifiants, les membres ou la facturation demande toujours une personne connectée.

**Que devient une clé quand la personne qui l’a créée quitte l’équipe ?**
Rien : une clé appartient à l’espace de travail, pas à la personne qui l’a créée, si bien qu’une intégration ne casse pas à son départ. Révoquez depuis la console les clés dont vous ne voulez plus ; chacune indique sa dernière utilisation, et une clé révoquée est refusée dès son appel suivant.

**L’API va-t-elle changer sous mon intégration ?**
Pas au sein de /v1. Les changements additifs — un nouvel endpoint, un nouveau champ dans une réponse — ont lieu dans /v1 ; tout ce qui pourrait casser une intégration qui fonctionne passe en /v2, et /v1 continue de répondre.