---
title: Introduction
excerpt: "Présentation de l'API REST CX-Engine : architecture, URLs de base, authentification et gestion des erreurs."
order: 1
---

## 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](/fr/docs/cx-api/authentication)). 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 :

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

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

```json
{
  "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 :

```json
{
  "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.