Intégrer avec un agent IA

Cette page rassemble, pour un agent IA qui écrit ou exécute une intégration, ce que le reste de la documentation explique page par page. Donnez-la-lui en premier : elle lui évite les erreurs que l'API ne signale pas.

Ce qu'il faut lui donner à lire

• L'index de la documentation, fait pour un agent : chaque page dans sa version Markdown, rangée en essentiels, démarrage rapide, définitions des objets, puis le guide de l'application.

  Copier

  https://staging-app.docage.com/llms.txt

• Si l'agent n'a que l'adresse de l'API : https://staging-api.docage.com/llms.txt, où renvoie aussi la racine https://staging-api.docage.com/. Il dit où lire la référence de l'API sans la charger d'un bloc, et cite l'index de cette documentation.

• Toute la partie API en un fichier, dans l'ordre de lecture : https://staging-app.docage.com/llms-full.txt.

• N'importe quelle page en Markdown : son adresse suivie de .md, par exemple https://staging-app.docage.com/documentation/api/commencer.md. Ses liens mènent à la version Markdown des autres pages.

• La référence de l'API, au format OpenAPI 3.1, qui décrit chaque route, ses paramètres, ses corps et ses réponses. Chaque route y porte un identifiant (operationId), le nom qu'un SDK engendré ou un outil lui donne. Elle se lit sous trois formes :

  • l'index des routes, en Markdown : une ligne par route (méthode, chemin, titre, identifiant), rangées par groupe puis par contrôleur. C'est par lui qu'un agent commence :

    Copier

    https://staging-api.docage.com/openapi/v2-fr/index.md

  • un document par contrôleur, autonome : ses routes et tout ce qu'elles citent, de quoi tenir dans le contexte d'un agent. Son adresse est donnée sous chaque contrôleur de l'index, par exemple https://staging-api.docage.com/openapi/v2-fr/Contacts.json ;

  • le document complet, https://staging-api.docage.com/openapi/v2-fr.json, pour générer un client. Il pèse plusieurs mégaoctets : un agent ne le lit pas d'un bloc.

  Les contrôleurs se rangent en cinq groupes (x-tagGroups) : signature et preuve, clients et ventes, communication, documents, organisation.

• Pour composer un flux d'automatisation : le chapitre Composer un flux, écrit pour un agent ou un script.

Les mots de l'écran et ceux de l'API

Celui qui confie la tâche parle avec les mots de l'application ; l'API nomme ses fiches en anglais. Chaque page des définitions des objets donne la correspondance ; les plus courantes :

S'authentifier

• Par la clé API d'un utilisateur, en authentification Basic (email:clé), ou par un jeton demandé par POST https://staging-api.docage.com/Account/CreateToken, valable 24 heures et prolongé par POST https://staging-api.docage.com/Account/refreshtoken — voir S'authentifier.
• La clé API n'ouvre aucune session : un agent qui l'emploie n'est jamais compté comme une connexion simultanée. Avec un jeton, gardez le même et prolongez-le : chaque jeton demandé ouvre une connexion, et deux connexions de l'API employées dans la même minute sont facturées.
• L'agent agit au nom de cet utilisateur, avec tous ses droits : une clé API ne se restreint pas. Donnez-lui un utilisateur dont les droits suffisent à la tâche, jamais un administrateur par commodité.
• Un agent qui lit des contenus écrits par des tiers — emails reçus, réponses de formulaire, messages — peut y trouver des instructions qui ne viennent pas de vous. Faites confirmer par un humain ce qui part à l'extérieur ou ne se défait pas : un envoi, le lancement d'un parcours, une suppression définitive.

Lire

• Une liste porte ses réglages dans le corps, et se lit par la méthode QUERY :

  HTTPcURLC#JavaScript

  Copier

  QUERY https://staging-api.docage.com/Contacts
  Authorization: Basic cHJlbm9tLm5vbUBleGFtcGxlLmNvbTp2b3RyZS1jbGUtYXBp
  Content-Type: application/json
  
  { "Filter": { "PropertyName": "Email", "Comparison": "=", "Value": "camille.martin@example.com" }, "Take": 10, "EntityProperties": ["Id", "FirstName", "LastName"] }

  La même lecture répond aussi au GET, mais beaucoup de clients HTTP ne transmettent pas le corps d'un GET — et sans corps, la liste rend tout ce que l'utilisateur voit. Préférez QUERY, et donnez toujours Take.

• L'en-tête Docage-TotalItems dit combien la liste compte de fiches en tout ; Skip avance de page en page.

• Un filtre qui ne se lit pas — une propriété inconnue, une valeur d'un autre type — ne retient aucune fiche ; une propriété de tri inconnue est ignorée. Une liste vide inattendue se relit critère par critère : voir Lire des listes.

• EntityProperties restreint les propriétés rendues : une liste longue se lit bien plus vite, et tient dans le contexte de l'agent.

• GET https://staging-api.docage.com/Contacts/{id} rend la fiche entière, ou null — avec le code 200 — pour une fiche qui n'existe pas et pour une fiche que l'utilisateur ne voit pas : testez le corps autant que le code. Pour n'en lire que quelques propriétés, filtrez la liste sur son Id avec EntityProperties.

Écrire

• POST envoie la fiche et rend son identifiant ; PUT https://staging-api.docage.com/Contacts/{id} n'envoie que les propriétés modifiées — voir Créer et modifier.
• Les noms de propriétés sont exacts, en PascalCase (FirstName, ParentOrganizationId), tels que la référence les écrit.
• Le serveur ignore sans erreur une propriété inconnue, une valeur qui ne se convertit pas dans son type, une propriété en lecture seule, et à la création une propriété qu'il écrit lui-même. La réponse ne le dit pas : après une écriture qui compte, relisez la fiche et comparez. Les définitions des objets disent, propriété par propriété, ce qui est obligatoire, en lecture seule ou écrit par le serveur.
• Une liaison se pose par l'identifiant de la fiche liée, jamais par un nom : un contact se rattache à sa société par ParentCompanyId. Son Company, le nom de la société, est recopié par le serveur depuis la société liée et ne rattache rien.
• Les énumérations s'écrivent en nombres ; la référence donne le libellé de chaque valeur.
• Les dates portent leur fuseau (Z ou un décalage) ; une date sans fuseau est lue en UTC — voir Dates et fuseaux.
• Les champs personnalisés s'écrivent dans CustomFieldsUserData, par nom technique ; attention, un CustomFieldsUserData dont toutes les valeurs sont vides efface toutes les valeurs de la fiche : voir Champs personnalisés.
• Un contact qui ressemble à une fiche existante peut être refusé (409), selon les règles de dédoublonnage de l'organisation : le corps de la réponse liste les fiches proches.

Ne rien faire deux fois

Une création rejouée après une coupure crée une seconde fiche. Donnez à chaque fiche que vous créez l'identifiant qu'elle a chez vous (ExternalId), et cherchez-la par lui avant de rejouer ; créez un parcours ou un email en deux temps (enregistrer, puis lancer ou envoyer) ; traitez un webhook une seule fois par son en-tête webhook-id. Voir Rejouer une requête sans doublon.

Décider sur le code d'état

L'agent décide d'après le code d'état, jamais d'après le message, rédigé pour un humain dans la langue de l'utilisateur et dont la formulation peut changer : il le montre ou le journalise. 400 et 422 se corrigent d'après le message ; 401 demande un nouveau jeton ; 403 ne se réessaie pas tel quel ; 409 demande de relire la fiche ; 429, 502 et 503 se réessaient avec une attente croissante. Voir Erreurs et Limites de débit.

Être prévenu plutôt que guetter

Pour suivre un changement — un parcours signé, une fiche créée —, abonnez-vous à un webhook plutôt que de relire la fiche en boucle : GET https://staging-api.docage.com/Webhooks/Catalog liste les types de fiches et les événements, POST https://staging-api.docage.com/Webhooks/{id}/Test envoie un appel d'essai. Vérifiez la signature de chaque appel, et répondez vite par un code 2xx.

Essayer sans risque

Une organisation qui n'est pas encore en production crée des parcours d'essai : sans consommation de crédits, aux documents filigranés et sans valeur probante. Voir Environnement d'essai.

Une intégration écrite pour la V1 de l'API, celle de 2025, se met à jour d'après Migration V1 > V2 : chaque rupture, et ce qu'il faut faire.

Confier une demande à l'assistant de l'utilisateur

Quand l'organisation l'offre, votre agent peut aussi confier une demande en langage naturel à l'assistant IA de l'utilisateur, qui connaît l'application et fait confirmer ce qui ne se défait pas. C'est utile pour une tâche ponctuelle ; une intégration qui doit se comporter toujours de la même façon appelle l'API.

Une consigne à lui donner

À coller en tête des instructions de votre agent :

Tu intègres l'API de Docage (https://staging-api.docage.com).
1. Commence par lire https://staging-app.docage.com/llms.txt, puis la page « Intégrer avec un agent IA ».
2. Cherche chaque route dans https://staging-api.docage.com/openapi/v2-fr/index.md, puis lis le document de son contrôleur : n'invente ni route ni propriété.
3. Lis les listes par QUERY, toujours avec Take et EntityProperties.
4. Après chaque écriture qui compte, relis la fiche : l'API ignore sans erreur ce qu'elle ne sait pas écrire.
5. Pose chaque liaison par l'identifiant de la fiche liée, jamais par un nom.
6. Décide d'après le code d'état ; garde le message pour l'humain.
7. Donne un ExternalId à ce que tu crées, et cherche-le avant de rejouer une création.
8. Essaie dans une organisation d'essai avant d'agir pour de vrai, et fais confirmer par un humain ce qui part à l'extérieur.