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, le widget chat embarqué, le serveur MCP (Claude Desktop / Cursor) et toute intégration tierce.

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 cdg1 (Paris).

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.

API key (programmatique)

Pour les intégrations serveur à serveur, génère une clé depuis Dashboard → API & Intégrations → Nouvelle clé. Format : ak_ suivi de 32 caractères hex. Les clés MCP (issues du flow OAuth Claude Desktop) utilisent le préfixe mcp_.

Authorization: Bearer ak_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Les clés sont scopées au tenant client_id qui les a créées. Ne les commit jamais dans un repo public. Révoque immédiatement une clé compromise depuis le dashboard — la révocation prend effet en moins d’une seconde.

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

Toutes les routes 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 (signup, verify-code)	5 requêtes / IP	60 s
LLM (copilot, simulator, MCP)	20-30 requêtes / user	60 s
Lectures (`/billing/usage`, metrics)	60 requêtes / user	60 s
Webhooks entrants (Stripe, Shopify…)	Vérification HMAC	—

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 tickets/voice du mois

Export GDPR

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

Référence

Endpoints

Base URL

Authentification

Bearer JWT (session utilisateur)

API key (programmatique)

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)

​API key (programmatique)

​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)

API key (programmatique)

Secret partagé (engine interne)

Rate limiting

Format des réponses

Succès

Erreur

Idempotence

Versioning

Ressources