Présentation de l'API REST

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://<votre-url>/api/v2`
Authentification	`Authorization: Bearer <token>`
Format	JSON. Envoyez `Content-Type: application/json` avec chaque corps de requête.
Contrat	Document OpenAPI 3.1

Remplacez <votre-url> 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).
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).

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

Dans plnnrly, ouvrez Accès API dans le menu utilisateur (en haut à droite, sous votre nom) et choisissez Créer un token.
Donnez un Nom au token.
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.
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.
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.
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. 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) 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) 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 : les autorisations du token ne couvrent pas l'opération. Utilisez un token aux autorisations plus larges.
insufficient-permission : votre rôle n'a pas le droit nécessaire. Demandez à un administrateur de modifier votre rôle.
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) 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.

Terminal

curl https://<votre-url>/api/v2/ \
  -H "Authorization: Bearer <token>" \
  -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 à 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é.

Pour aller plus loin

Prise en main (en anglais) : d'un token à votre première requête d'écriture.
Présentation de la référence (en anglais) : comment la référence est organisée, et tous les guides.
Erreurs et nouvelles tentatives (en anglais) : chaque type d'erreur et ce qu'il faut faire.
/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. Il accède aux mêmes opérations que vous, sauf l'envoi de fichiers, sans aucun client à écrire.