API des workflows : accès, scopes, création en brouillon et journaux

L’API Workflows permet de lire des définitions, préparer des modifications et consulter des journaux. Son accès reste limité à des sous-comptes activés. L’erreur 403 WORKFLOW_API_NOT_ENABLED_FOR_LOCATION indique que l’API n’est pas activée pour le compte concerné ; ajouter des permissions au token ne suffit pas à lever cette restriction.

Choisir le compte et les permissions

Utilisez un token OAuth ou d’intégration privée du sous-compte ciblé, avec Authorization: Bearer …. Pour les endpoints v3 documentés, envoyez l’en-tête Version: v3 et le bon locationId. Ne mélangez pas la version de l’API et le compteur de version d’une définition.

Accordez uniquement les capacités nécessaires. Une intégration qui prépare des brouillons n’a pas besoin de droits de publication ou de suppression.

Préparer un workflow en brouillon

1. Confirmez l’activation de l’API sur un compte de démonstration.
2. Consultez les types d’étapes et leurs schémas ; ne construisez pas une action à partir de son seul libellé.
3. Préparez une définition complète avec name, source, triggers, actions et edges.
4. Appelez POST /workflows/definition/validate. Une réponse HTTP 200 peut contenir valid: false : contrôlez le corps et les avertissements.
5. Après correction, créez avec POST /workflows/. La création est toujours en draft ; relevez workflowId et relisez la définition retournée.
6. Ouvrez le brouillon dans l’interface et vérifiez les déclencheurs, branches, attentes et destinataires avant toute publication distincte.

Pour modifier un workflow existant, conservez d’abord sa définition et son état. Réutilisez le compteur version renvoyé par la lecture sans l’inventer ni l’incrémenter vous-même. En cas de conflit, relisez la version actuelle et réconciliez les changements.

Lire les journaux

Utilisez l’identifiant du workflow, pas son nom, avec GET /workflows/:workflowId/logs. Les dates doivent être fournies ensemble en UTC et espacées de 30 jours maximum ; la rétention documentée est de 60 jours. Pour la page suivante, reprenez le curseur retourné avec les mêmes dates et filtres.

Un journal vide signifie qu’aucun événement n’a correspondu à la requête. Vérifiez période, contact et workflow avant de conclure à une panne. Pour une étape échouée, examinez son statut, ses métadonnées et sa correspondance avec l’action de la définition.

Conserver une preuve exploitable

Journalisez l’identifiant de requête, le compte, l’opération et le résultat sans enregistrer le token. Pour un incident, fournissez ces références et une définition expurgée des secrets. Gardez l’ancienne définition pour pouvoir préparer un retour au comportement précédent après revue.

La validation structurelle ne prouve pas l’efficacité du parcours métier ni la livraison des messages. Lorsqu’une création réussit mais ne renvoie pas de définition relue, retrouvez le workflow par son identifiant et contrôlez son état avant de continuer ; ne répétez pas aveuglément la création. Les API évoluent : prenez les schémas et en-têtes de la version de documentation effectivement utilisée, sans confondre Version: v3 et le compteur de concurrence version.