Guide intégrateur | Documentation Conformitly

L’interface de Conformitly s’appuie sur une API REST, que vous pouvez aussi appeler directement pour automatiser une tâche, alimenter un tableau de bord ou synchroniser un inventaire. Ce guide décrit son fonctionnement réel, y compris ses limites actuelles.

L’essentiel


Adresse de base	`https://api.conformitly.fr/api/v1`
Format	JSON (UTF-8), propriétés en camelCase
Authentification	jeton d’accès JWT d’un compte utilisateur, envoyé dans l’en-tête `Authorization: Bearer …`
Version	préfixe d’URL `/api/v1/` ; c’est la seule version existante
Référence	Référence de l’API, générée depuis le code du backend

api.conformitly.com redirige vers api.conformitly.fr (redirection 308). Appelez directement api.conformitly.fr : beaucoup de clients HTTP retirent l’en-tête Authorization lorsqu’ils suivent une redirection vers un autre domaine.

Ce que l’API ne propose pas encore

Il vaut mieux le savoir avant de concevoir une intégration :

Pas de clé d’API ni de compte de service. L’API s’utilise avec les identifiants d’un utilisateur réel, comme l’interface. Une intégration agit donc au nom de cet utilisateur, avec ses rôles. Les clés d’API sont prévues (ticket #37) mais n’existent pas aujourd’hui.
Pas de webhooks. La plateforme ne pousse aucun événement vers un système externe. Les seuls canaux sortants sont les notifications en temps réel destinées à l’interface (Notifications en temps réel) et les e-mails.
Pas de SDK ni de documentation interactive (Swagger) : l’API n’expose pas de document OpenAPI en production. Le document utilisé pour cette référence est téléchargeable : openapi.json.
Pas d’engagement de disponibilité (SLA) publié pour l’API.

Premier appel

Avec un compte sans double authentification :

# 1. Se connecter : la réponse contient le jeton d'accès
curl -s -X POST https://api.conformitly.fr/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"[email protected]","password":"••••••••••••"}'
# {"accessToken":"eyJ…","expiresIn":900,"session":{…},"requiresTwoFactor":false,"twoFactorToken":null}

# 2. Appeler l'API avec ce jeton
curl -s https://api.conformitly.fr/api/v1/auth/me \
  -H "Authorization: Bearer eyJ…"

L’option -c cookies.txt conserve le cookie de renouvellement, qui permet d’obtenir un nouveau jeton sans redonner le mot de passe : voir Authentification.

La plupart des ressources métier sont rattachées à une entité de l’organisation et se trouvent sous /api/v1/entities/{entityId}/…. Les entités sur lesquelles vous avez un rôle figurent dans le jeton (revendication roles) ; GET /api/v1/entities renvoie les entités visibles avec leur identifiant. Voir Organisation, entités et permissions.

Navigateur ou serveur

L’API n’accepte les appels depuis un navigateur (CORS) que s’ils viennent de l’application Conformitly elle-même (https://app.conformitly.fr). Une page web hébergée ailleurs ne peut pas l’appeler. Les appels de serveur à serveur (script, back-office, outil d’automatisation) ne sont pas concernés par CORS.

Pages de ce guide

Authentification : connexion, double authentification, jeton d’accès, renouvellement, sessions.
Organisation, entités et permissions : comment l’API détermine ce que vous pouvez lire et modifier.
Limites de débit : les limiteurs et la réponse 429.
Erreurs : les formats de réponse d’erreur, tels qu’ils existent.
Conventions : dates, énumérations, pagination, suppression, fichiers.
Notifications en temps réel : le canal SignalR utilisé par l’interface.
Référence de l’API : chaque opération, ses paramètres et ses schémas.