# Présentation de l'API REST Ce qu'est l'API REST de plnnrly, où elle se trouve, comment vous authentifier et comment obtenir un token. L'API REST permet à votre propre code de lire et de modifier vos données plnnrly : projets, éléments de travail, heures, documents Drive, clients, factures, congés, planification et plus encore. Elle échange du JSON en HTTPS, sur l'adresse plnnrly propre à votre organisation. Cette page résume l'essentiel en français. Les guides de l'API et la référence sont en anglais. ## Informations de connexion | Paramètre | Valeur | | -------------------- | ---------------------------------------------------------------------------- | | **URL de base** | `https:///api/v2` | | **Authentification** | `Authorization: Bearer ` | | **Format** | JSON. Envoyez `Content-Type: application/json` avec chaque corps de requête. | | **Contrat** | [Document OpenAPI 3.1](https://developers.plnnrly.com/openapi.json) | Remplacez `` par l'adresse où vous vous identifiez sur plnnrly, par exemple `acme.plnnrly.com`. Si votre organisation utilise son propre domaine, utilisez ce domaine : l'API n'est joignable qu'à cette adresse exacte et ne redirige jamais. Il n'existe pas d'adresse commune `api.plnnrly.com`. Dans plnnrly, **Accès API** dans le menu utilisateur ouvre la page **Tokens API**, qui affiche votre URL de base, prête à copier. ## Deux façons de s'authentifier | Vous développez | Utilisez | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Des scripts et des intégrations pour vous-même ou pour votre organisation | Un token d'accès personnel, que vous créez dans plnnrly. Voir [Tokens API (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/). | | Une application que d'autres personnes installent et à laquelle elles s'identifient | L'identification OAuth : le flux authorization code avec PKCE, et l'application s'enregistre elle-même. Pour les applications de bureau et en ligne de commande ; la personne qui s'identifie doit avoir le droit **Gérer les tokens API**. Voir [Identification OAuth (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/guides/oauth-apps/). | Dans les deux cas, chaque requête agit au nom d'une personne, avec ses droits et rien de plus. Les applications qui utilisent l'identification OAuth ne peuvent pas supprimer via l'API REST. ## Obtenir un token 1. Dans plnnrly, ouvrez **Accès API** dans le menu utilisateur (en haut à droite, sous votre nom) et choisissez **Créer un token**. 2. Donnez un **Nom** au token. 3. Sous **Autorisations**, choisissez **Lecture**, **Écriture** ou **Suppression** ; la liste ne propose que ce que vos droits permettent. L'écriture inclut la lecture, et la suppression inclut l'écriture et la lecture. Le token les enregistre sous la forme `api:read`, `api:write` et `api:destroy`, ou par ressource, comme `api:read:projects`, quand vous remplissez **Ressources**. 4. Laissez **Ressources** vide pour accorder les autorisations sur toutes les ressources, ou choisissez les parties de plnnrly auxquelles le token est limité. La liste ne propose que les parties sur lesquelles vous avez des droits. 5. Renseignez **Expire le**. Ce champ est obligatoire : il est prérempli avec une date située 90 jours après aujourd'hui, et la date ne peut pas dépasser 12 mois à partir d'aujourd'hui. 6. Copiez le token. Il n'est affiché qu'une seule fois. **Accès API** n'apparaît dans le menu utilisateur que si l'API REST est activée et que vous détenez le droit **Gérer les tokens API**. Voir [qui peut créer des tokens](https://developers.plnnrly.com/fr/docs/administration/#permissions). Vous pouvez avoir dix tokens actifs à la fois. Le champ **Autorisations** fixe les autorisations du token : ce que le token peut faire. Ce n'est pas la même chose que les droits que vous donne votre rôle. Les deux s'appliquent : un token ne fait donc jamais plus que ce que vous pouvez faire dans plnnrly. Le guide [Tokens API (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/) couvre le renouvellement, la révocation et le formulaire complet. ## Chaque opération indique ce dont elle a besoin Chaque page d'opération de la [référence (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/) indique les autorisations du token et le droit plnnrly dont elle a besoin, ainsi que son coût sur votre limite de débit. Les autorisations et le droit sont vérifiés à chaque requête, et le type d'une réponse `403` indique ce qui l'a refusée : - [insufficient-token-scope](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-token-scope) : les autorisations du token ne couvrent pas l'opération. Utilisez un token aux autorisations plus larges. - [insufficient-permission](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-permission) : votre rôle n'a pas le droit nécessaire. Demandez à un administrateur de modifier votre rôle. - [forbidden-by-policy](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#forbidden-by-policy) : vous n'avez pas le droit de faire cela sur cet enregistrement précis. ## Voir ce que votre organisation expose La requête de [découverte (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/discovery/) liste ce que votre organisation expose : chaque ressource, avec ses URL et ses opérations. N'importe quel token API personnel peut l'appeler ; elle ne demande aucun droit. ```bash curl https:///api/v2/ \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` L'en-tête `Accept` est facultatif : omettez-le, ou envoyez `application/json`. La découverte laisse de côté les parties de plnnrly que votre organisation n'utilise pas, comme la facturation. Elle ne vérifie pas quelles ressources sont couvertes par les autorisations de votre token ou par votre rôle : une ressource listée peut donc tout de même renvoyer `403`. ## Quand l'API est désactivée Un administrateur peut désactiver l'API REST dans **Paramètres › Administration › MCP & API**. Tant qu'elle est désactivée, l'API répond `404` [endpoint-not-found](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#endpoint-not-found) à chaque requête, y compris aux requêtes envoyées avec un token qui fonctionnait auparavant. Voir [ce qui se passe quand un réglage est désactivé](https://developers.plnnrly.com/fr/docs/administration/#when-switched-off). ## Pour aller plus loin - [Prise en main (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/) : d'un token à votre première requête d'écriture. - [Présentation de la référence (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/) : comment la référence est organisée, et tous les guides. - [Erreurs et nouvelles tentatives (en anglais)](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/) : chaque type d'erreur et ce qu'il faut faire. - [/openapi.json](https://developers.plnnrly.com/openapi.json) : le contrat complet, pour les générateurs de code et les outils. ## Pour les assistants IA Si vous voulez qu'un assistant IA travaille avec vos données plnnrly, utilisez le [serveur MCP](https://developers.plnnrly.com/fr/docs/mcp/). Il accède aux mêmes opérations que vous, sauf l'envoi de fichiers, sans aucun client à écrire.