Documentation › L’API REST
Connecter une autre application : l'API REST
Votre ERP, votre SIRH ou vos propres scripts peuvent lister vos process publiés, lancer des instances de process avec leurs valeurs et suivre leur avancement, sans que personne n'ouvre SerenForce. Ils s'identifient avec une clé d'API de votre organisation.
L'API REST est incluse dans l'offre Business. Avec une offre inférieure, la page affiche seulement Not included in your plan et l'API refuse les appels. Seuls les administrateurs de l'organisation gèrent ses clés d'API.
1. Créer une clé d'API
- Ouvrez le menu Settings, puis, dans la rubrique Administration, API keys.
- Cliquez sur New API key, donnez un Name qui dit ce qui l'utilise (par exemple « SIRH ») et choisissez une Expiry : Never, dans 30 jours, 90 jours ou un an.
- Cliquez sur Create the key. La clé s'affiche une seule fois : copiez-la avec Copy the key et rangez-la en lieu sûr (le coffre de secrets de votre autre application), puis cliquez sur I have copied the key.
Ensuite, la liste ne montre plus que le début de la clé (pn_1a2b3c4d…), son état (Active, Expired, Revoked), sa date d'expiration et sa dernière utilisation. SerenForce ne garde qu'une empreinte de la clé : si vous la perdez, créez-en une nouvelle et révoquez l'ancienne.
2. Ce qu'une clé peut faire
Une clé agit dans cette organisation, au nom de l'administrateur qui l'a créée, avec des droits limités :
- lister les process publiés et voir ce qu'un lancement peut renseigner (variables modifiables, participants) ;
- lancer une instance de process ;
- suivre les instances de process lancées et leurs tâches (état, valeurs des variables, dates).
Elle ne termine aucune tâche (c'est la personne à qui la tâche est assignée qui la fait), ne modifie aucun process et n'administre rien. Elle ne voit jamais une autre organisation. Elle cesse de fonctionner quand elle est révoquée, quand elle expire, ou quand son créateur n'administre plus l'organisation.
3. Appeler l'API
La page API keys affiche l'Address of the API de votre organisation, de la forme https://…/api/votre-organisation/public/v1, avec un bouton pour la copier. Chaque appel envoie la clé dans l'en-tête Authorization: Bearer votre-clé (ou X-Api-Key: votre-clé). Exemples avec curl :
# Les process publiés
curl -H "Authorization: Bearer pn_votre-clé" https://…/api/votre-organisation/public/v1/processes
# Lancer une instance de process
curl -X POST -H "Authorization: Bearer pn_votre-clé" -H "Content-Type: application/json" \
-d '{"processId":"…","name":"Intégration de Marie","variables":[{"name":"Ordinateur","value":"MacBook"}],"participants":[{"name":"Manager","email":"paul@exemple.com"}]}' \
https://…/api/votre-organisation/public/v1/process-instances
# Suivre l'instance de process et ses tâches
curl -H "Authorization: Bearer pn_votre-clé" https://…/api/votre-organisation/public/v1/process-instances/…/tasks
- Seules les variables que le process laisse modifier au lancement prennent une valeur ; pour une liste, donnez les noms des options séparés par des virgules.
- Un participant est joué par la personne dont vous donnez l'email ; sinon par sa personne par défaut. Les personas sont joués par leur titulaire.
- Le lien OpenAPI document de la page ouvre la description complète de l'API (format OpenAPI, que les outils comme Postman ou Swagger importent).
4. Les réponses à connaître
- 401 : la clé est absente, inconnue, révoquée ou expirée.
- 402 : l'offre de l'organisation n'inclut pas l'API REST, ou l'abonnement est terminé.
- 403 : le créateur de la clé n'a pas la permission (par exemple lancer des instances de process).
- 400 : une valeur ne convient pas au process ; le message dit laquelle.
- 429 : plus de 120 appels par minute avec la même clé ; attendez le nombre de secondes donné par l’en-tête
Retry-Afteravant de recommencer.
Chaque lancement fait par une clé apparaît dans le journal d'audit au nom de son créateur.
5. Révoquer une clé
Cliquez sur Revoke à côté de la clé, puis confirmez. Les applications qui l'utilisent sont refusées tout de suite ; la clé reste dans la liste (Revoked) pour garder une trace. Pour leur rendre l'accès, créez une nouvelle clé.