Documentation

Brancher vos outils sur vos opérations

Tout ce que Marketingtool sait faire est accessible par trois portes qui partagent le même jeu d’outils et les mêmes droits : une API REST, un serveur MCP pour les assistants, et la fenêtre de discussion intégrée. Ce qu’une personne ne peut pas faire, son programme ne le peut pas non plus.

Les clés et les droits

Une clé se crée depuis votre espace, page Clés d’API. Elle s’affiche une seule fois : notez-la à ce moment-là, nous n’en gardons qu’une empreinte.

curl https://projetmarketing.com/api/v1/me \
  -H "Authorization: Bearer mkt_xxxxxxxx_…"

Une clé agit au nom d’une personne, jamais au nom de l’organisation.

Le niveau d’accès effectif est le plus faible des deux : celui que vous donnez à la clé, et celui que son porteur possède aujourd’hui. Rétrograder quelqu’un rétrograde ses clés à l’instant même, et le désactiver les éteint. C’est ce qui fait que la même question posée par le graphiste et par la direction ne renvoie pas la même chose.

Un appelant ne voit que les outils qu’il peut utiliser. Ce filtrage est une politesse : le contrôle réel est refait à l’exécution, et deviner le nom d’un outil qu’on ne vous a pas annoncé se solde par un 403.

Démarrer en trois requêtes

Toutes les réponses ont la même forme : { "ok": true, "resultat": … } ou { "ok": false, "erreur": …, "code": … }. Les dates s’écrivent YYYY-MM-DD.

1. Savoir ce que la clé permet

L’API se décrit elle-même. Ce point d’accès renvoie les outils ouverts à votre clé, avec le schéma de leurs paramètres : c’est de quoi construire une intégration sans lire cette page.

curl https://projetmarketing.com/api/v1/tools -H "Authorization: Bearer mkt_…"

2. Lire l’état d’une opération

Les opérations et les livrables se désignent par leur identifiant ou par leur nom, même partiel. Si plusieurs correspondent, l’API refuse et vous dit lesquelles plutôt que de choisir à votre place.

curl "https://projetmarketing.com/api/v1/operations/black%20friday" \
  -H "Authorization: Bearer mkt_…"

3. Faire avancer un livrable

curl -X POST "https://projetmarketing.com/api/v1/operations/black%20friday/deliverables/newsletter%20d'ouverture/status" \
  -H "Authorization: Bearer mkt_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Terminer un livrable débloque en cascade ceux qui l’attendaient, et prévient les personnes concernées. Vous n’avez rien d’autre à appeler.

Les points d’accès

Toutes les adresses sont préfixées par https://projetmarketing.com/api/v1. Les paramètres marqués « adresse » se placent dans l’URL, les autres dans le corps JSON.

GET/meTout membre

Renvoie l’identité de l’appelant : son nom, son organisation, son niveau d’accès, ses rôles métier et ce qu’il a le droit de faire. À appeler en premier pour savoir à qui l’on parle.

GET/toolsTout membre

Énumère les outils que votre clé peut appeler, avec leurs paramètres. L’API se décrit elle-même : c’est le point de départ d’une intégration.

GET/operationsLecteur minimum

La liste des opérations de l’organisation, avec leurs dates, leur avancement, ce qui les bloque et leurs étiquettes.

POST/operationsÉditeur minimum

Crée une opération. Sans modèle, elle ne contient que son brief. Avec le modèle « Opération commerciale », elle arrive avec sa chaîne complète de livrables.

namecorps: Le nom de l’opération, par exemple « Black Friday 2026 ».
starts_atcorps: Premier jour, au format YYYY-MM-DD.
ends_atcorpsfacultatif: Dernier jour, au format YYYY-MM-DD. Facultatif.

GET/operations/:operationLecteur minimum

L’état détaillé d’une opération : chaque livrable avec son type, son métier responsable, qui s’en occupe, son état (bloqué, à faire, en validation, fait), ce qu’il attend et ses pièces jointes.

operationadresse: Identifiant ou nom de l’opération, même partiel.

POST/operations/:operation/deliverablesÉditeur minimum

Ajoute un livrable à une opération. Le type détermine sa couleur, son métier responsable et son délai de préparation.

operationadresse: Identifiant ou nom de l’opération. Facultatif : à omettre si vous ne le connaissez pas, plutôt que d’inventer.
titlecorps: L’intitulé du livrable.
typecorpsfacultatif: Nom du type, par exemple « Newsletter » ou « SMS ». Facultatif.
publish_atcorpsfacultatif: Date de diffusion, YYYY-MM-DD. Facultatif.
depends_oncorpsfacultatif: Intitulés des livrables dont celui-ci dépend. Facultatif.

PATCH/operations/:operation/deliverables/:deliverableÉditeur minimum

Modifie l’intitulé, les notes ou les dates d’un livrable.

operationadresse: Identifiant ou nom de l’opération. Facultatif : à omettre si vous ne le connaissez pas, plutôt que d’inventer.
deliverableadresse: Identifiant ou intitulé du livrable.
titlecorpsfacultatif: Nouvel intitulé. Facultatif.
notescorpsfacultatif: Ce qu’il faut savoir pour le produire. Facultatif.
publish_atcorpsfacultatif: Date de diffusion, YYYY-MM-DD. Facultatif.
due_atcorpsfacultatif: Échéance interne, YYYY-MM-DD. Facultatif.

POST/operations/:operation/deliverables/:deliverable/statusÉditeur minimum

Marque un livrable comme fait, à faire, ou en attente de validation. Le passer à « fait » débloque ce qui l’attendait et prévient les personnes concernées.

operationadresse: Identifiant ou nom de l’opération. Facultatif : à omettre si vous ne le connaissez pas, plutôt que d’inventer.
deliverableadresse: Identifiant ou intitulé du livrable.
statuscorps: todo, in_review ou done.

POST/operations/:operation/deliverables/:deliverable/claimÉditeur minimum

L’appelant se saisit d’un livrable. Il en devient responsable et disparaît de la liste des autres personnes du même métier.

operationadresse: Identifiant ou nom de l’opération. Facultatif : à omettre si vous ne le connaissez pas, plutôt que d’inventer.
deliverableadresse: Identifiant ou intitulé du livrable.

GET/my-workTout membre

Ce qui attend l’appelant, toutes opérations confondues : les livrables débloqués qui relèvent de ses rôles métier ou qu’il s’est attribués. C’est la réponse à « qu’est-ce que je dois faire ? ». TOUT ce que renvoie cet outil lui revient : une liste non vide veut dire qu’il a du travail, même si personne ne s’est encore nommé dessus.

GET/catalogTout membre

Le catalogue de l’organisation : les types de livrable disponibles et les étiquettes d’opération. Utile avant de créer quelque chose.

Le serveur MCP

La même adresse rend les mêmes outils à Claude, à ChatGPT ou à tout client compatible MCP. Ajoutez-la comme connecteur, avec votre clé en jeton, et vous pouvez demander où en est une opération ou faire ajouter une étape en langage courant.

https://projetmarketing.com/api/mcp

C’est du JSON-RPC 2.0 en HTTP. Trois méthodes suffisent : initialize, tools/list et tools/call. La liste renvoyée est déjà filtrée par les droits de la clé — 10 outils au maximum.

curl -X POST https://projetmarketing.com/api/mcp \
  -H "Authorization: Bearer mkt_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_operation",
                 "arguments":{"operation":"black friday"}}}'

Une erreur métier — référence introuvable, droit manquant — revient dans le résultat avec isError, et non comme un échec de transport : le modèle doit pouvoir lire ce qui n’a pas marché et le reformuler, pas voir sa connexion tomber.

Les erreurs

Le code est stable et fait pour être testé ; le message est écrit pour être lu par un humain et peut changer.

Code	HTTP	Ce que ça veut dire
`missing_api_key`	401	L’en-tête `Authorization: Bearer mkt_…` manque.
`bad_api_key`	401	La clé est inconnue, révoquée, ou son porteur n’est plus membre.
`forbidden`	403	Le porteur de la clé n’a pas le droit d’appeler cet outil. En deviner le nom ne suffit pas.
`not_found`	404	Aucune route ne correspond à cette méthode et ce chemin.
`unknown_tool`	404	Cet outil n’existe pas.
`operation_not_found`	404	Aucune opération ne correspond à la référence donnée.
`action_not_found`	404	Aucun livrable ne correspond à la référence donnée.
`ambiguous_operation`	400	Plusieurs opérations correspondent. Le message énumère les candidates : l’API préfère demander plutôt que choisir à votre place.
`ambiguous_action`	400	Plusieurs livrables correspondent. Le message les énumère.
`bad_status`	400	Statut inconnu. Les valeurs admises sont `todo`, `in_review` et `done`.
`bad_date`	400	Une date n’est pas au format YYYY-MM-DD.
`bad_json`	400	Le corps de la requête n’est pas du JSON valide.
`self_dependency`	400	Un livrable ne peut pas dépendre de lui-même.
`internal`	500	Erreur inattendue de notre côté. Le détail n’est jamais renvoyé au client.