Trackily Docs

API HTTP

Trackily expose deux APIs distinctes : MCP (recommandé pour les agents LLM, cf. /docs/mcp) et HTTP REST classique (recommandé pour les intégrations machine-to-machine, webhooks externes, et postbacks affiliate). Cette section documente la deuxième.

Concept

L'API HTTP de Trackily a quatre familles d'endpoints :

  1. Admin API (/admin/api/*) — pilote toute l'instance. Auth par cookie de session admin (HTTP-only, signé HMAC) + permission check par section. Préfère le MCP pour piloter : moins de boilerplate, scopes plus fins, audit log natif.
  2. Public tracking (/c/:slug, /lp/:slug, /r/:slug) — sert les redirects de tracking et les landings. C'est le hot path de l'app, optimisé pour la perf.
  3. Postback (/postback) — endpoint universel de réception des conversions affiliate. Cf. Postback.
  4. Webhooks ENTRANTS (/webhook/*) — endpoints qui RECEIVENT des events de Shopify, Stripe, PayPal, Mailgun, etc. Cf. Webhooks.

À noter : Trackily n'émet PAS de webhooks sortants (du moins, pas via un système de souscription générique). Toute la propagation d'événement vers l'extérieur passe par d'autres chemins : conversion triggers email, postbacks vers les ad networks, script tags Shopify injectés.

Auth des endpoints /admin/api/*

L'admin API est protégée par authMiddleware qui :

  1. Lit le cookie tly_admin_session (signé HMAC avec SECRETS_MASTER_KEY)
  2. Vérifie la signature + la fraîcheur (TTL configurable, par défaut 7 jours)
  3. Lit users.id depuis le cookie, charge le user row
  4. Pour les endpoints requirePermission(section, action), vérifie que le user a la permission (table user_permissions JSONB)

Pour s'authentifier en POST initial :

POST /admin/api/login HTTP/1.1
Content-Type: application/json

{ "email": "admin@example.com", "password": "..." }

Réponse : Set-Cookie: tly_admin_session=...; HttpOnly; SameSite=Lax (Secure en HTTPS).

Les calls suivants passent le cookie automatiquement. Pour un script externe : extraire le cookie après login, le rejouer dans le header Cookie:.

Pour les agents LLM, préfère MCP qui a un système de bearer + scopes + rate limiting + audit dédié.

Format des réponses

Convention :

// Success
{ "ok": true, ...payload }
// ou directement le payload (pas d'enveloppe)

// Erreur
{ "error": "description courte" }
// ou
{ "ok": false, "error": "..." }

Status HTTP standard :

  • 200 — succès
  • 400 — payload invalide / validation échouée
  • 401 — pas authentifié
  • 403 — authentifié mais permission manquante
  • 404 — ressource introuvable
  • 429 — rate limited
  • 500 — erreur serveur

Rate limiting

Limites importantes en place côté serveur :

Endpoint Limite
POST /admin/api/login 5 essais / 15 min / IP (loginRateLimit)
GET /postback 600 / minute / IP (postbackRateLimit)
POST /api/account/magic-link ~10 / minute / IP (pixelRateLimit)
POST /api/lead ~10 / minute / IP
Tracking pixels ~30 / min / IP

Le rate limiter est en mémoire process (pas Redis) — si tu tournes plusieurs instances derrière un LB, chaque process a son propre compteur.

CORS

Par défaut, /admin/api/* n'a pas de CORS (même-origin uniquement). Les endpoints publics (/api/account/*, /postback, /api/lead) ont une allowlist configurable dans Settings.

Endpoints publics utiles

GET /postback

Réception des conversions affiliate. Cf. Postback.

POST /api/lead

Soumission de form (landing). Body : email, name, et tout champ custom. Crée une leads row + (si la landing est bound à une email_list) enroll dans la liste.

POST /api/lead HTTP/1.1
Content-Type: application/x-www-form-urlencoded

email=marie@example.com&name=Marie&landing_id=42&city=Paris

Réponse : 200 { ok: true, redirect_url: "/r/..." }.

POST /api/account/magic-link

Magic-link customer auth. Cf. Magic Link.

GET /pixel.js, GET /trackily.js, GET /cloak.js, GET /i18n.js

Static JS assets servis avec cache headers. Le pixel pixel.js capture les page views côté landing, trackily.js est la lib client pour les events custom, cloak.js est le pilote du cloaking.

GET /mcp et POST /mcp

L'endpoint MCP. Cf. /docs/mcp/concept.

Différences MCP vs Admin REST

Aspect MCP Admin REST
Auth Bearer token tly_ap_<...> Cookie session HTTP-only
Granularité perms 42 scopes 8 sections × {read, write}
Audit log autopilot_audit_log (chaque call) logs/syslog seulement
Rate limiting per-token, 2 buckets (default + ai) per-IP global
Découvrabilité tools/list retourne tout en JSON-Schema OpenAPI spec à parser séparément
Tier-2 (confirm) natif absent — chaque endpoint exécute direct
Idempotency natif sur Tier-2 absent (à toi de gérer côté client)
Compatibilité LLM excellent médiocre (le LLM compose à la main)

Si tu écris un script qui doit appeler 5-10 endpoints, MCP est plus simple. Si tu écris un webhook handler côté ton infra qui doit pinguer Trackily, REST est plus naturel.

Voir aussi