API Actero

L’API Actero te permet d’envoyer des événements à l’agent Actero, de récupérer ta consommation, d’exporter tes données, et de t’abonner aux événements émis par la plateforme. Elle est consommée par le dashboard React et le widget chat embarqué. Pour brancher ton IA (Claude, ChatGPT, Cursor…) ou un développeur sur ta boutique, passe par le serveur MCP : voir Authentication.

Base URL

https://actero.fr/api

Toutes les routes sont HTTPS uniquement. HTTP est redirigé en 308. La résolution DNS pointe sur Vercel ; les fonctions sont des Vercel Functions Node.js exécutées dans la région fra1 (Francfort).

Les endpoints Supabase Edge Functions (/functions/v1/*) ne sont pas publics. Ils sont uniquement appelés en interne par le serveur Node ou par les webhooks Stripe signés. Considère https://actero.fr/api comme la seule surface API publique.

Authentification

L’API accepte trois schémas d’authentification, selon le contexte :

Bearer JWT (session utilisateur)

Utilisé par le dashboard React. Tu récupères le token via supabase.auth.getSession() côté client et tu l’envoies en header :

Authorization: Bearer <supabase_jwt>

Le JWT expire après 1 h. Le SDK Supabase rafraîchit automatiquement.

Jeton développeur (serveur MCP)

Pour une intégration serveur à serveur (script, Zapier, Make, n8n), crée un jeton développeur depuis Dashboard → IA et API → L’API (dès Starter, pour la personne propriétaire et les managers). Format : mcp_pat_…, valable 30, 90 ou 365 jours, affiché une seule fois. Il ouvre le serveur MCP (https://actero.fr/api/mcp), qui sert d’API : les mêmes outils que ton IA, avec les mêmes droits et le même journal. Il n’ouvre aucune autre route.

Authorization: Bearer mcp_pat_…

Un jeton vaut pour une seule boutique. Ne le commit jamais dans un dépôt public et ne le colle jamais dans ton thème. Révoque immédiatement un jeton compromis depuis IA et API.

Secret partagé (engine interne)

Les routes du moteur (/api/engine/gateway, connecteurs internes) acceptent aussi un secret en header x-engine-secret ou x-internal-secret. Réservé aux workers internes Actero ; tu n’en as pas besoin pour intégrer.

Rate limiting

Les routes sensibles sont rate-limitées. Les limites varient selon la nature de la route :

Type de route	Limite	Fenêtre
Engine gateway (par client)	200 messages	60 min
Engine gateway (par email customer)	10 messages	10 min
Auth (envoi du code, vérification)	5 à 15 requêtes / IP	1 h
Copilote	30 requêtes / user	60 s
Serveur MCP	300 requêtes / connexion	60 s
Webhooks entrants (Stripe, Shopify…)	Vérification HMAC	—

Les lectures (/billing/usage, /client/export-data) n’ont pas de limite de débit propre. Dépassement → 429 Too Many Requests. Voir Rate limits pour la stratégie de retry.

Format des réponses

Toutes les réponses sont JSON UTF-8 :

Content-Type: application/json; charset=utf-8

Succès

Le format dépend de l’endpoint, mais la convention est de retourner directement le payload sans enveloppe :

{
  "event_id": "evt_01H...",
  "run_id": "run_01H...",
  "status": "completed",
  "classification": "order_status",
  "confidence": 0.92
}

Erreur

{
  "error": "Quota de tickets épuisé. Achetez des crédits ou passez à un plan supérieur.",
  "tickets_used": 50,
  "tickets_limit": 50,
  "upgrade_url": "https://actero.fr/pricing"
}

Sentry capture automatiquement les 5xx ; le request_id exposé dans certaines réponses est l’event ID Sentry. Partage-le au support pour tracer.

Idempotence

Les webhooks entrants (Stripe, Shopify, Gorgias…) sont dédupliqués par (provider, event_id) pendant 30 jours. Si ton upstream réessaie, Actero retourne 200 sans ré-exécuter. Pour les requêtes côté engine/gateway, utilise un event_id stable dans le payload : nous insérons une ligne engine_events par appel, donc deux POST identiques créent deux events. La dé-duplication métier (ex. ticket Shopify déjà traité) est faite par le Brain en amont via external_ticket_id.

Versioning

L’API n’est pas encore versionnée publiquement. Tout changement breaking est annoncé 30 jours à l’avance par email + bannière dashboard. Les ajouts de champs dans les réponses ne sont jamais considérés breaking — code défensivement.

Ressources

Authentication

Détails des trois schémas d’auth

Webhooks sortants

S’abonner aux événements émis par l’agent

Rate limits

Limites, headers, retry strategy

Engine gateway

Envoyer un événement à l’agent

Billing & usage

Consommation de tickets du mois

Export GDPR

Récupérer toutes les données du tenant

Référence

Endpoints

Base URL

Authentification

Bearer JWT (session utilisateur)

Jeton développeur (serveur MCP)

Secret partagé (engine interne)

Rate limiting

Format des réponses

Succès

Erreur

Idempotence

Versioning

Ressources

Authentication

Webhooks sortants

Rate limits

Engine gateway

Billing & usage

Export GDPR

​Base URL

​Authentification

​Bearer JWT (session utilisateur)

​Jeton développeur (serveur MCP)

​Secret partagé (engine interne)

​Rate limiting

​Format des réponses

​Succès

​Erreur

​Idempotence

​Versioning

​Ressources

Authentication

Webhooks sortants

Rate limits

Engine gateway

Billing & usage

Export GDPR

Base URL

Authentification

Bearer JWT (session utilisateur)

Jeton développeur (serveur MCP)

Secret partagé (engine interne)

Rate limiting

Format des réponses

Succès

Erreur

Idempotence

Versioning

Ressources