--- title: Prérequis pour le Middleware CX-Engine excerpt: Ce que l'API REST de votre ERP ou CRM doit exposer pour le connecteur générique de CX-Engine — remontée de fiche, création de contact, journalisation des appels et des chats. order: 5 --- ## À qui s'adresse cette page Cette page s'adresse à l'équipe de développement de votre ERP ou CRM lorsque votre système ne fait **pas** partie des intégrations natives (Dynamics 365, Salesforce, HubSpot, Pipedrive, Loji). Le [connecteur REST générique](/fr/faq/crm-middleware/supported-integrations) de CX-Engine permet de connecter n'importe quel système exposant une API, à condition que cette API implémente un petit ensemble de routes spécifiques, afin que le Middleware puisse l'interroger et y écrire lors des événements PBX (appels entrants, appels sortants, sessions de chat). Vous n'avez pas besoin de reproduire le format de l'API de CX-Engine elle-même — le connecteur générique se configure visuellement (URL des points d'entrée, authentification, mapping des champs) depuis l'interface CX-Engine. L'essentiel est que votre système expose des routes permettant d'effectuer les opérations suivantes. ## Authentification Votre API doit supporter l'une des méthodes suivantes, ce sont celles avec lesquelles le connecteur générique peut être configuré : | Méthode | Description | |---|---| | **OAuth 2.0 Client Credentials** | Authentification serveur à serveur via une paire `client_id` / `client_secret`. Recommandée pour les configurations sans interface. | | **Basic Auth (HTTP)** | Nom d'utilisateur / mot de passe envoyés à chaque requête. | | **Clé API** | Clé statique envoyée en en-tête ou en paramètre de requête. | Quelle que soit la méthode choisie, les identifiants sont saisis une seule fois dans le menu **Intégrations** de CX-Engine et utilisés pour chaque requête suivante vers votre API. ## Routes requises ### Remontée de fiche (Contact Lookup) — recherche par numéro de téléphone ou email **Usage :** Appelée lors de la remontée de fiche lorsqu'un appel sonne sur le PBX, afin que CX-Engine puisse afficher la fiche client correspondante à l'agent avant même qu'il ne décroche. Votre API a besoin d'une route acceptant un numéro de téléphone et/ou une adresse email, et renvoyant les contacts correspondants. **Format suggéré** `GET /contacts/search?phone={phone}&email={email}` | Champ de réponse | Description | |---|---| | `id` | Identifiant unique du contact dans votre système | | `first_name` / `last_name` | Nom du contact | | `email` | Email du contact | | `phone_business` / `phone_mobile` | Numéros de téléphone, pour permettre à CX-Engine de matcher sur l'un ou l'autre | | `company` | Nom de l'entreprise, affiché dans la remontée de fiche | | `entity_url` | URL directe vers la fiche du contact dans votre système, utilisée pour l'ouvrir en un clic | > Si un appel arrive et qu'aucun contact ne correspond, renvoyez un `404`. CX-Engine utilise ce code pour basculer sur son mode « contact factice » (dummy), afin que la journalisation de l'appel puisse tout de même se poursuivre. ### Création de contact **Usage :** Appelée lorsqu'un agent choisit de créer une nouvelle fiche pour un appelant non reconnu, directement depuis la remontée de fiche CX-Engine. **Format suggéré** `POST /contacts` | Champ | Requis | Description | |---|---|---| | `last_name` | oui | Nom | | `first_name` | non | Prénom | | `email` | non | Adresse email | | `phone_business` / `phone_mobile` | non | Numéros de téléphone | | `call_direction` | non | `inbound` ou `outbound` — sens de l'appel à l'origine de la création | Votre API doit renvoyer la fiche créée (a minima son `id`) afin que CX-Engine puisse y rattacher l'appel. ### Recherche d'utilisateur — trouver un utilisateur par email **Usage :** Le PBX ne fournit que l'adresse email de l'agent. Si la journalisation des appels dans votre système nécessite un `user_id` pour rattacher l'appel à un utilisateur/agent précis, CX-Engine a besoin d'une route pour résoudre cet email vers votre identifiant utilisateur interne. **Format suggéré** `GET /users/search?email={email}` | Champ de réponse | Description | |---|---| | `id` | Identifiant unique de l'utilisateur dans votre système | | `email` | Adresse email de l'utilisateur | ### Journal des appels (Call Logging) — enregistrer un appel terminé **Usage :** Appelée lorsqu'un appel se termine sur le PBX, afin qu'il apparaisse comme une activité/un historique rattaché à la bonne fiche dans votre système. C'est le cœur de la fonctionnalité de journalisation automatique des appels. **Format suggéré** `POST /calls` | Champ | Description | |---|---| | `direction` | `inbound`, `outbound`, ou `internal` | | `status` | ex. `completed`, `no-answer`, `busy` | | `number_from` / `number_to` | Numéros appelant et appelé | | `duration` | Durée de l'appel | | `start_time` / `end_time` | Horodatages de l'appel (UTC) | | `agent_email` | Email de l'agent ayant traité l'appel | | `user_id` | Identifiant utilisateur interne de l'agent, résolu via la route de recherche d'utilisateur ci-dessus, si votre fiche d'appel en a besoin | | `recording_url` | URL de l'enregistrement de l'appel, si votre offre inclut l'enregistrement | | `linked_contact_id` | L'`id` du contact renvoyé par la route de remontée de fiche, si une correspondance a été trouvée | #### Mise à jour d'un appel **Usage :** Certaines données ne sont pas encore disponibles lorsque l'appel se termine — des informations PBX supplémentaires récupérées dans un second temps, ou une transcription/un résumé IA généré de façon asynchrone. Votre API a besoin d'une route pour mettre à jour la fiche d'appel déjà créée, plutôt que d'exiger un nouveau `POST` pour chaque donnée supplémentaire. **Format suggéré** `PUT /calls/{id}` Accepte les mêmes champs que `POST /calls`, appliqués en mise à jour partielle de l'appel identifié par `{id}` — l'identifiant renvoyé par votre système lors de la journalisation initiale de l'appel. #### Champs IA Si votre offre CX-Engine inclut le module Insights AI, les appels sont également enrichis avec des données générées par IA — transcription, résumé, sentiment, sujets, etc. Ces données ne sont généralement pas prêtes lorsque l'appel se termine, elles sont donc envoyées via la route de mise à jour `PUT /calls/{id}` ci-dessus une fois la transcription terminée. Consultez les champs **AI & Transcription** dans [Configurer le Middleware](/fr/docs/middleware-crm/configure-middleware#champs-disponibles) pour la liste complète des champs que vous pouvez choisir de mapper et de stocker. ### Journal des chats (optionnel) **Usage :** Si votre PBX / centre de contact gère également le chat en direct, le même principe s'applique — une route pour enregistrer une session de chat terminée, rattachée à un contact. `POST /chats` | Champ | Description | |---|---| | `email` | Adresse email du client, utilisée pour matcher ou créer un contact | | `number_external` | Identifiant externe du client, si aucun email n'est disponible | | `chat_messages` | Transcription ou résumé de la conversation | | `start_time` / `end_time` | Horodatages du chat | | `agent_email` | Agent ayant traité le chat | ## Conventions de réponse - Utilisez les codes de statut HTTP standards : `200`/`201` pour un succès, `4xx` pour les erreurs client (requête invalide, ressource introuvable), `401`/`403` pour les erreurs d'authentification/autorisation. - Renvoyez du JSON pour chaque réponse, y compris les erreurs. - Pour les routes de liste ou de recherche, renvoyez un tableau vide plutôt qu'un `404` en l'absence de résultat. La route de remontée de fiche fait exception : renvoyez un `404` pour permettre à CX-Engine de basculer sur son mode « contact factice » (voir ci-dessus). ## Étapes suivantes Une fois que votre API expose ces routes, un administrateur peut configurer la connexion depuis le menu **Intégrations** de CX-Engine — voir [Connecter l'intégration CRM](/fr/docs/middleware-crm/connect-integration) — puis faire correspondre les champs de votre API avec ceux de CX-Engine depuis le menu **CRM Connector** > **Settings** — voir [Configurer le Middleware](/fr/docs/middleware-crm/configure-middleware).