Navigation
API CX-Engine · 3 min de lecture

Introduction

Présentation de l'API REST CX-Engine : architecture, URLs de base, authentification et gestion des erreurs.

#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.)

#Ressources disponibles

Page Endpoints
Authentification OAuth 2.0, connexion, déconnexion, changement de token
Clients Comptes clients, identification du compte, paramètres régionaux
CRM Lookup Recherche et création de contacts, journalisation des appels et chats dans le CRM connecté
Historique des appels Appels reçus par CX-Engine
Utilisateurs, Rôles & Invitations Utilisateurs, rôles, organisations, invitations
Contacts Contacts des comptes clients
Clés d'intégration Clés d'intégration CRM d'un client
Smart Routings Règles entrantes, groupes, plages horaires, exceptions, lookups, tokens CFD
Smart Routings : CTI, Contacts, Routage géographique, Enquêtes Autres ressources Smart Routings

#Endpoints scopés au client

De nombreux endpoints du workspace agissent sur un seul compte client (lookups CRM, historique des appels, clés d'intégration, Smart Routings). Le client n'est pas déduit du token : indiquez-le avec le paramètre de requête customer_account. Voir Choix du compte client.

#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.