> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction à l'API

> S'authentifier auprès de l'API REST et commencer à développer

L'API REST Famulor permet de gérer les mêmes ressources client que celles disponibles dans le tableau de bord : assistants, appels, campagnes, transcriptions, connaissances et paramètres d'espace de travail.

<Tip>
  Pour un processus métier en plusieurs étapes — enrichir un prospect, puis appeler, puis mettre à jour un CRM, puis notifier un canal —, une [automatisation](/fr/automations/overview) demande souvent moins de code à maintenir que de connecter vous-même chaque étape. Utilisez l'API directement lorsque vous avez besoin d'un contrôle programmatique simple et immédiat, comme déclencher un appel unique depuis votre propre application.
</Tip>

## URL de base

```text theme={null}
https://app.famulor.io/api/v1
```

Si vous utilisez un domaine en marque blanche, remplacez `app.famulor.io` par ce domaine. Les chemins restent identiques.

## Accès à l'API

Les requêtes REST nécessitent **API Access** dans le forfait de l'espace de travail ou sous forme d'option récurrente. Si cet accès est retiré, les clés API et identifiants OAuth existants restent consultables et révocables par les administrateurs de l'espace de travail, mais les requêtes `/api/v1` ordinaires renvoient `403 api_access_required`.

Après l'échec d'un paiement de forfait, `POST /api/v1/billing/invoice-payment` et `POST /api/v1/billing/portal` restent disponibles avec un identifiant valide afin qu'un propriétaire puisse régulariser la facturation. Les contrôles d'authentification, de rôle et de portée continuent de s'appliquer.

## Authentification

Envoyez un jeton Bearer dans l'en-tête `Authorization` :

```bash theme={null}
curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"
```

Deux types d'identifiants sont pris en charge :

* **Workspace API keys** (`fam_...`) — créez-les sous **Settings → API & MCP** pour les intégrations serveur à serveur. La clé complète n'est affichée qu'une seule fois. Le tableau de bord n'offre pas de sélecteur de portées, donc une clé qui y est créée porte toujours toutes les portées. Pour générer une clé plus restreinte, appelez `POST /api/v1/api-keys` ou `POST /api/v1/workspaces/{workspace_id}/api-keys` avec un tableau `scopes` explicite — les portées de la nouvelle clé doivent être un sous-ensemble de celles de l'identifiant qui la crée.
* **OAuth 2.0 access tokens** (`fam_at_...`) — utilisez Authorization Code avec PKCE-S256 pour les applications agissant au nom d'un utilisateur connecté.

L'accès autorisé par un utilisateur suit son appartenance et son rôle actuels dans l'espace de travail. Les clés API d'espace de travail continuent de suivre leur propre statut et leurs propres portées jusqu'à ce qu'un administrateur autorisé de l'espace de travail les révoque.

<Warning>
  Traitez les clés API comme des mots de passe. Ne les intégrez jamais dans du code de navigateur ou d'application mobile ; utilisez OAuth pour les applications destinées aux utilisateurs.
</Warning>

### Hygiène des clés

* Stockez les clés dans des variables d'environnement ou un gestionnaire de secrets, jamais dans le contrôle de version.
* Limitez chaque clé au strict nécessaire pour l'intégration — une clé qui ne fait que lire les appels ne devrait pas aussi avoir `assistants:write`. Les clés créées depuis le tableau de bord ont toujours un accès complet ; utilisez le chemin API ci-dessus pour en générer une aux portées restreintes.
* Faites tourner les clés périodiquement, et immédiatement après le départ de toute personne y ayant accès.
* Révoquer une clé depuis **Settings → API & MCP** prend effet immédiatement ; les requêtes déjà en cours peuvent tout de même aboutir.

### Exigences des clients OAuth

Un client développé sur mesure pilote directement les points de terminaison d'autorisation et de jeton :

```text theme={null}
https://app.famulor.io/api/oauth/authorize
https://app.famulor.io/api/oauth/token
```

Utilisez des URL de redirection HTTPS. Les applications natives peuvent aussi utiliser des adresses HTTP de bouclage littérales telles que `127.0.0.1`. Les demandes d'autorisation OAuth doivent utiliser PKCE-S256 et ne demander que les portées enregistrées pour le client. En cas de limitation de débit, réessayez après le délai indiqué par la réponse.

Le client utilise soit des identifiants préapprouvés pour votre espace de travail, soit s'enregistre lui-même dynamiquement avec `POST /api/oauth/register` — en fournissant entre 1 et 10 `redirect_uris` uniques. Les points de terminaison, les portées prises en charge et les types d'octroi sont détectables via `/.well-known/oauth-authorization-server`.

Les jetons d'accès se renouvellent avec l'octroi `refresh_token`. Les jetons de rafraîchissement changent à chaque utilisation : demander un nouveau jeton d'accès émet aussi un nouveau jeton de rafraîchissement et invalide immédiatement celui que vous avez envoyé.

## Format des réponses

Les réponses réussies placent le résultat dans `data` et peuvent inclure `meta` :

```json theme={null}
{
  "data": [{ "id": "…", "name": "Support Agent" }],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}
```

Les réponses ne contiennent que des données d'espace de travail destinées au client. Les secrets ne sont jamais renvoyés après leur enregistrement, et les valeurs sensibles sont masquées lorsque c'est utile. Les enregistrements sont fournis via des liens temporaires. L'usage et la facturation sont exprimés dans les minutes et crédits affichés sur votre compte.

## Pagination

Les points de terminaison de liste utilisent `limit` et `offset` :

| Paramètre | Valeur par défaut | Maximum | Description                  |
| --------- | ----------------- | ------- | ---------------------------- |
| `limit`   | `50`              | `200`   | Nombre d'éléments à renvoyer |
| `offset`  | `0`               | —       | Nombre d'éléments à ignorer  |

Utilisez `meta.pagination.total` pour déterminer si d'autres pages sont disponibles.

## Erreurs

Les échecs renvoient un code stable et un message lisible :

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "A destination phone number is required."
  }
}
```

| Statut | Code                  | Signification                                                   |
| ------ | --------------------- | --------------------------------------------------------------- |
| `400`  | `invalid_request`     | Corps ou paramètres de requête invalides                        |
| `401`  | `unauthorized`        | Identifiant manquant, invalide, expiré ou révoqué               |
| `403`  | `forbidden`           | La portée, le rôle ou le forfait n'autorise pas l'action        |
| `403`  | `api_access_required` | API Access n'est pas disponible pour cet espace de travail      |
| `404`  | `not_found`           | Ressource introuvable ou non visible pour cet espace de travail |
| `409`  | `conflict`            | La ressource est dans un état conflictuel                       |
| `429`  | `rate_limited`        | Trop de requêtes ; patientez puis réessayez                     |
| `500`  | `internal_error`      | Erreur inattendue                                               |

## Gestion des clients en marque blanche

Les revendeurs autorisés peuvent utiliser les points de terminaison `platform` pour gérer leurs propres clients finaux, émettre et révoquer des jetons API client, transférer des crédits, et gérer leur domaine personnalisé. Ces points de terminaison nécessitent les portées `platform:read` ou `platform:write` ; les opérations sur le domaine personnalisé utilisent la portée de paramètres correspondante.

| Point de terminaison                            | Objectif                                                                   |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| `GET /api/v1/platform/users`                    | Lister vos clients finaux                                                  |
| `POST /api/v1/platform/users`                   | Inscrire un client final                                                   |
| `GET /api/v1/platform/users/{user_id}`          | Lire le résumé de compte d'un client final                                 |
| `POST /api/v1/platform/users/{user_id}/token`   | Émettre un jeton API pour ce client                                        |
| `POST /api/v1/platform/users/login`             | Authentifier un client                                                     |
| `POST /api/v1/platform/users/{user_id}/logout`  | Révoquer les jetons API de ce client                                       |
| `POST /api/v1/platform/users/{user_id}/balance` | Transférer des crédits entre votre solde revendeur et le client            |
| `GET /api/v1/custom-domain`                     | Lire l'état du domaine personnalisé                                        |
| `POST /api/v1/custom-domain`                    | Ajouter un domaine personnalisé et recevoir les enregistrements DNS requis |
| `POST /api/v1/custom-domain/verify`             | Vérifier le DNS et activer un domaine prêt                                 |
| `DELETE /api/v1/custom-domain`                  | Supprimer le domaine personnalisé                                          |

Consultez le [guide de l'API marque blanche](/fr/admin/whitelabel-api) pour des exemples.

## MCP

Les mêmes fonctionnalités destinées aux clients sont disponibles sous forme d'outils IA via le [point de terminaison MCP](/fr/api/mcp) :

```text theme={null}
https://app.famulor.io/mcp
```

MCP utilise les mêmes clés API, le même consentement OAuth, les mêmes portées et le même accès aux espaces de travail. Sa disponibilité est contrôlée séparément par **Connect AI / MCP**, et non par API Access.