Vue d'ensemble

L'API CX-Engine est une API REST qui retourne des réponses JSON. Elle est divisée en deux couches distinctes qui reflètent l'architecture multi-tenant de la plateforme :

  • API centrale — opérations au niveau du compte (inscription, connexion, gestion des espaces de travail, invitations)
  • API workspace — opérations au niveau du tenant (clients, contacts, utilisateurs, clés d'intégration, etc.)

URLs de base

Couche URL de base
API centrale https://{domaine-central}/api
API workspace https://{sous-domaine}.{domaine-central}/api

Le sous-domaine du workspace est attribué lors de la création de l'espace de travail (ex. monentreprise.cx-engine.app).

Authentification

Tous les endpoints authentifiés requièrent un token Bearer dans l'en-tête Authorization :

Authorization: Bearer {token}

Les tokens sont obtenus via l'endpoint /api/login (voir Authentification). Les tokens sont scopés : un token central ne fonctionne qu'avec l'API centrale, un token workspace ne fonctionne qu'avec l'API de ce workspace.

Pour basculer entre un token central et un token workspace, utilisez l'endpoint POST /api/switch-to.

Format des requêtes

Les endpoints d'écriture authentifiés (POST, PUT) attendent un corps JSON :

Content-Type: application/json

Format des réponses

Toutes les réponses sont des objets JSON. Les réponses réussies contiennent généralement directement les données demandées. Les réponses d'erreur suivent cette structure :

{
  "message": "Description lisible de l'erreur.",
  "error": "code_machine_readable"
}

Les erreurs de validation incluent un tableau hint avec les messages par champ :

{
  "response": "bad request: please check body parameters.",
  "hint": ["The name field is required."]
}

Codes HTTP

Code Signification
200 OK — requête réussie
201 Créé — ressource créée ou mise à jour
400 Mauvaise requête — requête malformée ou échec de validation
401 Non autorisé — token manquant ou invalide
403 Interdit — authentifié mais non autorisé
404 Non trouvé — la ressource n'existe pas
422 Non traitable — erreur de validation sémantique
500 Erreur interne du serveur

Pagination

Les endpoints de liste qui supportent la pagination retournent une réponse paginée standard :

{
  "data": [...],
  "current_page": 1,
  "last_page": 4,
  "per_page": 20,
  "total": 72
}

Passez ?per_page=N pour contrôler la taille de page et ?page=N pour naviguer entre les pages.

Authentification