Envoyer un parcours à signer
Tirer un parcours d'un modèle, y mettre la personne et le document, l'envoyer, puis suivre son statut.
Un parcours fait signer (valider, payer…) un ou plusieurs documents à une ou plusieurs personnes. Le plus simple est de partir d'un modèle de parcours, préparé dans l'application : ses participants, ses documents, ses réglages. L'API n'y met que ce qui change à chaque envoi — la personne, le document.
1Trouver le modèle
GET https://staging-api.docage.com/Transactions/TemplatesIdAndName
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…curl "https://staging-api.docage.com/Transactions/TemplatesIdAndName" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Transactions/TemplatesIdAndName");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
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/Transactions/TemplatesIdAndName", {
headers: {
Authorization: `Bearer ${token}`
}
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;[{ "Id": "aaaaaaaa-0000-4000-8000-000000000001", "Name": "Contrat de prestation", "IsSystem": false }]2Lire ses identifiants conviviaux
Chaque participant et chaque document d'un modèle a un identifiant convivial (FriendlyName) : « Client », « Contrat »… C'est
par lui que la création désigne ce qu'elle remplit.
GET https://staging-api.docage.com/Transactions/aaaaaaaa-0000-4000-8000-000000000001
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…curl "https://staging-api.docage.com/Transactions/aaaaaaaa-0000-4000-8000-000000000001" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Transactions/aaaaaaaa-0000-4000-8000-000000000001");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
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/Transactions/aaaaaaaa-0000-4000-8000-000000000001", {
headers: {
Authorization: `Bearer ${token}`
}
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;Relevez TransactionMembers[].FriendlyName (les participants) et TransactionFiles[].FriendlyName (les documents ; Type 0 =
à signer, 1 = annexe).
3Créer le parcours, en brouillon
Un seul appel, en multipart/form-data :
curl -X POST "https://staging-api.docage.com/Transactions/CreateFullTransaction?launchTransaction=false" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
-F "TemplateId=aaaaaaaa-0000-4000-8000-000000000001" \
-F 'Transaction={"Name":"Contrat de prestation – Atelier Lumière","TransactionMembers":[{"FriendlyName":"Client","SignMode":1}]}' \
-F 'Client={"FirstName":"Camille","LastName":"Martin","Email":"camille.martin@example.com","Mobile":"+33600000001"}' \
-F "Contrat=@contrat-atelier-lumiere.pdf;type=application/pdf" \
-F 'Client,Contrat={"Pages":"-1","Coordinates":"320,90,200,80"}'TemplateId: le modèle.Transaction(facultatif) : ce qui change au modèle, en JSON — le nom du parcours, et pour un participant désigné par son identifiant convivial, ses réglages (SignMode:1code par email,0code par SMS).- Une personne, sous l'identifiant convivial de son participant (
Client) : l'identifiant d'un contact ou d'un utilisateur que vous voyez, ou un contact en JSON (FirstName,LastName,Email,Mobile…). - Un document, sous son identifiant convivial (
Contrat) : un PDF, une image ou un document Word (converti en PDF). Il remplace celui du modèle ; sans fichier, celui du modèle est gardé. - Un emplacement de signature, sous « participant,document » (
Client,Contrat) :Pages(1,1-3,1;3,-1pour la dernière page,ALL,EXTRApour une page ajoutée à la fin) etCoordinates(x,y,largeur,hauteur, en points, depuis le coin inférieur gauche de la page). Il s'ajoute aux emplacements que le modèle pose déjà : chacun reçoit son encart.
La réponse est le parcours créé : gardez son Id, et ceux de ses participants (TransactionMembers[].Id) et de ses documents
(TransactionFiles[].Id). Chaque variante de cette requête — sans modèle, une personne nouvelle, un document rédigé dans Docage,
un participant de plus… — a son guide : voir Créer un parcours à partir d'un modèle et
Créer un parcours sans modèle.
4L'envoyer
POST https://staging-api.docage.com/Transactions/LaunchTransaction/cccccccc-0000-4000-8000-000000000003
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…curl -X POST "https://staging-api.docage.com/Transactions/LaunchTransaction/cccccccc-0000-4000-8000-000000000003" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Transactions/LaunchTransaction/cccccccc-0000-4000-8000-000000000003");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
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/Transactions/LaunchTransaction/cccccccc-0000-4000-8000-000000000003", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`
}
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;200 : le parcours est parti, chaque participant reçoit son invitation à son tour. 400 : l'envoi est refusé, le message dit
pourquoi (un participant sans email, un document qui manque…) ; le parcours reste en brouillon, corrigez-le et relancez. 404 : le
parcours est introuvable, ou vous ne le voyez pas ; 403 : vous le voyez sans avoir le droit de le modifier. Voir
Lancer le parcours.
À noter
Sans launchTransaction=false, la création envoie aussitôt. Un envoi refusé laisse alors le parcours en brouillon, et son
identifiant n'est donné que dans le message du refus : créez en brouillon, puis lancez.
5Suivre son statut
GET https://staging-api.docage.com/Transactions/cccccccc-0000-4000-8000-000000000003
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…curl "https://staging-api.docage.com/Transactions/cccccccc-0000-4000-8000-000000000003" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Transactions/cccccccc-0000-4000-8000-000000000003");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
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/Transactions/cccccccc-0000-4000-8000-000000000003", {
headers: {
Authorization: `Bearer ${token}`
}
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;GlobalStatus |
Statut |
|---|---|
0 |
Brouillon |
1 |
Programmé |
2 |
En cours |
3 |
Terminé |
4 |
Refusé |
5 |
Expiré |
6 |
Annulé |
-10 |
Erreur |
Chaque participant a aussi son GlobalStatus (2 en cours, 3 a tout fait, 4 a refusé), sa date de signature (SignDate) et,
s'il a refusé de signer, son motif (RefusalReason). Voir Lire le statut d'un parcours.
Plutôt que de relire le parcours, abonnez-vous à l'événement 20, « changement de statut du parcours » : voir
Être prévenu quand un parcours est signé.
6Relancer un participant
PUT https://staging-api.docage.com/TransactionMembers/SendReminder/dddddddd-0000-4000-8000-000000000004
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…curl -X PUT "https://staging-api.docage.com/TransactionMembers/SendReminder/dddddddd-0000-4000-8000-000000000004" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/TransactionMembers/SendReminder/dddddddd-0000-4000-8000-000000000004");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
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/TransactionMembers/SendReminder/dddddddd-0000-4000-8000-000000000004", {
method: "PUT",
headers: {
Authorization: `Bearer ${token}`
}
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;Le participant reçoit un rappel de sa prochaine action. PUT https://staging-api.docage.com/Transactions/SendReminders/{id} relance tous les participants
qui ont une action en attente.
- Annuler un parcours :
PUT https://staging-api.docage.com/Transactions/Abort/{id}— voir Annuler un parcours. - Le clore :
PUT https://staging-api.docage.com/Transactions/Terminate/{id}. - Les relances, une à une ou automatiques : Relancer les participants.
Une route qui modifie ne se sert jamais en GET : un lien ouvert, un aperçu de messagerie ou un robot qui suit les liens ne déclenche
rien.
Les pièges
- Une personne en JSON met à jour un contact existant. Le contact que désigne son
Id, sinon celui du participant du modèle, est modifié aussitôt, même si la création du parcours échoue ensuite ; sans l'un ni l'autre, un contact est créé. Pour une personne déjà connue, sans rien changer à sa fiche, envoyez plutôt l'identifiant de son contact. - Un compte d'essai ne fait pas signer par SMS :
SignMode1(code par email) ; ses documents portent un filigrane d'essai. - Chaque participant a besoin d'un email, d'un prénom et d'un nom ; une signature par SMS, d'un numéro de mobile. Ses emails
partent dans sa langue (
Language, le français d'office). - Donnez toujours
Pagesà un emplacement de signature : sans lui, il se pose sur la première page. - Ensuite : Télécharger les documents signés et la preuve.