Rédiger un document d'après son texte

Écrire un document ou un modèle de document en Markdown, y poser ses champs — données du parcours, valeurs à saisir, signature —, le corriger, puis le joindre à un parcours.

6 min de lecture Mise à jour le 12 novembre 2026

Le contenu d'un document de Docage est un fichier Word. Vous ne l'écrivez pas vous-même : l'API le compose d'après un texte en Markdown, et ses champs s'écrivent en jetons ({{…}}), que le serveur relève à chaque enregistrement. Un modèle de document sert ensuite à produire les documents d'un parcours : remplis des données du parcours, complétés par ses participants, signés.

1Écrire le document

POST https://staging-api.docage.com/Documents/FromText
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "Name": "Contrat de prestation",
  "Text": "# Contrat de prestation\n\nEntre {{Transaction_ParentOrganization_Name}} et {{TransactionMember[Client]_FirstName}} {{TransactionMember[Client]_LastName}}, le client.\n\n## Article 1 — Objet\n\nLa prestation commence le {{TransactionMember[Client]_Fill_DateDeDébut}}.\n\nSignature du client : {{TransactionMember[Client]_Signature}}",
  "IsTemplate": true,
  "TransactionTemplateId": "aaaaaaaa-0000-4000-8000-000000000001",
  "Language": 1
}

curl -X POST "https://staging-api.docage.com/Documents/FromText" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Contrat de prestation",
    "Text": "# Contrat de prestation\n\nEntre {{Transaction_ParentOrganization_Name}} et {{TransactionMember[Client]_FirstName}} {{TransactionMember[Client]_LastName}}, le client.\n\n## Article 1 — Objet\n\nLa prestation commence le {{TransactionMember[Client]_Fill_DateDeDébut}}.\n\nSignature du client : {{TransactionMember[Client]_Signature}}",
    "IsTemplate": true,
    "TransactionTemplateId": "aaaaaaaa-0000-4000-8000-000000000001",
    "Language": 1
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Documents/FromText");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Name": "Contrat de prestation",
      "Text": "# Contrat de prestation\n\nEntre {{Transaction_ParentOrganization_Name}} et {{TransactionMember[Client]_FirstName}} {{TransactionMember[Client]_LastName}}, le client.\n\n## Article 1 — Objet\n\nLa prestation commence le {{TransactionMember[Client]_Fill_DateDeDébut}}.\n\nSignature du client : {{TransactionMember[Client]_Signature}}",
      "IsTemplate": true,
      "TransactionTemplateId": "aaaaaaaa-0000-4000-8000-000000000001",
      "Language": 1
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Documents/FromText", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Name": "Contrat de prestation",
    "Text": "# Contrat de prestation\n\nEntre {{Transaction_ParentOrganization_Name}} et {{TransactionMember[Client]_FirstName}} {{TransactionMember[Client]_LastName}}, le client.\n\n## Article 1 — Objet\n\nLa prestation commence le {{TransactionMember[Client]_Fill_DateDeDébut}}.\n\nSignature du client : {{TransactionMember[Client]_Signature}}",
    "IsTemplate": true,
    "TransactionTemplateId": "aaaaaaaa-0000-4000-8000-000000000001",
    "Language": 1
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Name : le nom du document, 255 caractères au plus.
Text : son texte, 200 000 caractères au plus. Le Markdown en donne les titres (#, ##), les paragraphes, le gras, l'italique, les listes et les tableaux ; le document est en A4, en Arial 11. Une balise HTML s'écrit telle quelle, en texte, et une image est remplacée par son texte alternatif.
IsTemplate : true d'office, un modèle de document ; false, un document ordinaire.
TransactionTemplateId (facultatif) : le modèle de parcours pour lequel le document est écrit — un modèle de parcours actif de votre organisation, ou de la plateforme, que vous voyez. Un participant renommé dans ce modèle l'est aussi dans le document.
Language : sa langue (1 français, 0 anglais…) ; celle de l'utilisateur d'office.

La réponse dit ce que le serveur a relevé :

JSON

{
  "Id": "bbbbbbbb-0000-4000-8000-000000000002",
  "Fields": [
    { "Name": "Transaction_ParentOrganization_Name", "Kind": 0, "Member": null },
    { "Name": "TransactionMember[Client]_FirstName", "Kind": 0, "Member": null },
    { "Name": "TransactionMember[Client]_LastName", "Kind": 0, "Member": null },
    { "Name": "TransactionMember[Client]_Fill_DateDeDébut", "Kind": 1, "Member": "Client" },
    { "Name": "TransactionMember[Client]_Signature", "Kind": 2, "Member": "Client" }
  ],
  "IgnoredTokens": []
}

Fields liste les champs du document : Kind 0 une donnée remplie par la fusion, 1 une valeur qu'un participant saisit, 2 l'emplacement d'une signature ; Member nomme le participant qui saisit ou qui signe. IgnoredTokens liste les jetons qui ne sont pas des champs : ils resteront tels quels dans le document. Il doit être vide ; sinon, corrigez le texte (étape 3).

Un nom ou un texte vide, ou trop long, est refusé (400) ; un modèle de parcours (TransactionTemplateId) inconnu, que vous ne voyez pas, ou d'une autre organisation que le document, aussi (422).

2Les jetons

Jeton	Ce qu'il écrit
`{{TransactionMember[Client]_LastName}}`	Une donnée du participant « Client » : `FirstName`, `LastName`, `Email`, `Mobile`, `Phone`, `Company`, `Job`, `Address1`, `ZipCode`, `City`, `Country`…
`{{TransactionMember[Client]_Fill_Adresse}}`	Une valeur que le participant saisit pendant le parcours : son adresse, sa date de début… Le nom après `_Fill_` s'écrit sans espace, les accents sont permis.
`{{TransactionMember[Client]_Signature}}`	L'emplacement de sa signature : l'encart s'y pose quand le document devient le PDF à signer.
`{{Transaction_Name}}`, `{{Transaction_ParentOrganization_Name}}`	Le nom du parcours, celui de son organisation : dans un document de parcours, l'organisation se lit par le parcours (`{{Transaction_ParentOrganization_…}}` : `Name`, `Address1`, `ZipCode`, `City`…). `{{Organization_Name}}`, lu dans un email, n'y est pas rempli.
`[FORMAT("dd/MM/yyyy", {{Transaction_CreationDate}})]`	Une donnée mise en forme : ici, la date de création du parcours.

« Client » est l'identifiant convivial d'un participant du parcours (FriendlyName), sans espace. Un jeton dont la racine n'est pas une fiche de Docage — {{Poste}}, {{DateDuJour}} — n'est pas un champ : il rejoint IgnoredTokens. Une valeur propre à chaque document se fait saisir par un participant (_Fill_).

3Corriger, renommer, retrouver

Réécrire le texte : il remplace tout le contenu, et la réponse est la même qu'à l'étape 1.

PUT https://staging-api.docage.com/Documents/bbbbbbbb-0000-4000-8000-000000000002/FromText
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "Text": "# Contrat de prestation\n\n…" }

curl -X PUT "https://staging-api.docage.com/Documents/bbbbbbbb-0000-4000-8000-000000000002/FromText" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{"Text": "# Contrat de prestation\n\n…"}'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/Documents/bbbbbbbb-0000-4000-8000-000000000002/FromText");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Text": "# Contrat de prestation\n\n…"
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Documents/bbbbbbbb-0000-4000-8000-000000000002/FromText", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"Text": "# Contrat de prestation\n\n…"})
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Code	Ce qu'il dit
`400`	Le texte est vide ou trop long, ou le document est un tableur : il ne se réécrit pas d'après un texte.
`403`	Vous n'avez pas le droit de modifier le document, ou c'est un modèle système.
`404`	Le document est introuvable, ou vous ne le voyez pas.
`422`	C'est le document d'un parcours lancé, ou la copie de travail d'un parcours : il ne se modifie plus par sa fiche.

Renommer : PUT https://staging-api.docage.com/Documents/{id} avec { "Name": "…" }. Changer de modèle de parcours (TransactionTemplateId) suit la règle de la création (422).
Retrouver : GET https://staging-api.docage.com/Documents/TemplatesIdAndName pour les modèles, QUERY https://staging-api.docage.com/Documents pour la liste filtrée — voir Lire des listes. GET https://staging-api.docage.com/Documents/{id} rend la fiche, ses champs relevés dans Fields.
Les champs de plusieurs documents, sans leur contenu : POST https://staging-api.docage.com/Documents/Fields, avec la liste de leurs identifiants (["…", "…"]) ; la réponse donne, pour chacun, son Id et ses Fields. Un document inconnu, ou que vous ne voyez pas, en est absent, sans erreur.

4Le joindre à un parcours

Un document écrit pour un modèle de parcours n'y est pas joint pour autant. Il se joint à un parcours en brouillon, ou à un modèle de parcours, par son identifiant :

cURL

curl -X POST "https://staging-api.docage.com/TransactionFiles" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -F "TransactionId=cccccccc-0000-4000-8000-000000000003" \
  -F "InitialDocumentId=bbbbbbbb-0000-4000-8000-000000000002" \
  -F "Name=Contrat de prestation" \
  -F "FriendlyName=Contrat" \
  -F "Type=0"

Voir Ajouter un document pour les champs de ce formulaire. À la création d'un parcours depuis un modèle, le document se désigne aussi dans la clé Transaction : voir Remplacer un document par un modèle de document.

Le parcours doit ensuite avoir ce que le document attend :

un participant dont l'identifiant convivial est celui des jetons (« Client ») ;
pour une valeur à saisir, l'action « Remplissage du document » (Type 1) de ce participant. Elle lui est donnée d'office quand il est ajouté au parcours après le document (POST https://staging-api.docage.com/TransactionMembers) ; sinon, posez-la par POST https://staging-api.docage.com/TransactionActions, comme dans Ajouter un participant ;
pour une signature, son action « Signature » (Type 3, ou MemberRole à 0).

Au lancement (POST https://staging-api.docage.com/Transactions/LaunchTransaction/{id}), le parcours tire son propre document du modèle ; le participant y saisit ses valeurs sur sa page, puis le document, rempli des données du parcours, devient le PDF qu'on signe. Pour le télécharger rempli, voir Obtenir un document rempli depuis un modèle.

Les pièges

Un jeton ignoré reste dans le document, tel quel, sous les yeux du signataire : relisez IgnoredTokens après chaque écriture.
Un champ à saisir dont le participant manque au parcours fait refuser le lancement (400, « Des champs à remplir ne sont attribués à aucun participant du parcours… ») ; un participant qui a des champs à saisir sans l'action « Remplissage du document » aussi (« … a des champs à remplir dans un document, mais pas l'action « Remplissage du document » »).
Un document signé ne se modifie plus : le remplissage passe avant la première signature. D'office, le serveur l'y range ; le lancement refuse un ordre qui le placerait après.
Un tableur ne s'écrit pas d'après un texte : voir Écrire dans un tableur et lire ses calculs.
Un champ à saisir dont la liste d'options vient de fiches ou d'un tableur ne la montre au participant qu'une fois son exposition validée par un administrateur : GET https://staging-api.docage.com/Documents/{id}/Exposure en dit l'état, et la validation se donne ou se demande comme pour un formulaire (étape 5 de Créer un formulaire web), sous Documents/{id}/Exposure.