Créer un parcours à partir d'un modèle
Partir d'un modèle préparé dans l'application, et n'envoyer que ce qui change — la personne, le document, un réglage.
Un modèle de parcours porte tout ce qui se répète d'un envoi à l'autre : ses participants, leurs actions et leur ordre, ses
documents, ses emplacements de signature, ses emails, ses délais. Il se prépare dans l'application ; l'API en tire un parcours en une
requête, POST https://staging-api.docage.com/Transactions/CreateFullTransaction, en multipart/form-data, et n'y met que ce qui change.
Les clés du formulaire
| Clé | Valeur |
|---|---|
TemplateId |
L'identifiant du modèle. |
Transaction |
Facultatif : ce qui change, en JSON — une propriété du parcours, ou les réglages d'un participant, d'un observateur ou d'un document désigné par son identifiant convivial. |
L'identifiant convivial d'un participant ou d'un observateur (Client) |
La personne : l'identifiant d'un contact ou d'un utilisateur, ou un contact en JSON. |
L'identifiant convivial d'un document (Contrat) |
Un fichier : un PDF, une image ou un document Word (.docx), converti en PDF. |
« participant,document » (Client,Contrat) |
Un emplacement de signature, en JSON. |
Ajoutez ?launchTransaction=false à l'adresse pour créer le parcours en brouillon ; sans lui, il est envoyé aussitôt.
La réponse
200 rend le parcours entier, en JSON : son Id, ses participants (TransactionMembers), ses documents (TransactionFiles), ses
emplacements de signature (TransactionFields). Leurs identifiants sont neufs : ce sont ceux du parcours, pas du modèle.
Un envoi refusé répond 400 : « Le parcours a été enregistré en brouillon, mais son envoi est refusé (identifiant) : … ». Le parcours
existe : corrigez-le, puis lancez-le par POST https://staging-api.docage.com/Transactions/LaunchTransaction/{id}, sans le recréer. Une erreur avant
l'enregistrement répond 400 avec son motif, et rien n'est créé — sauf un contact existant mis à jour par sa clé, qui l'est aussitôt.
Les règles communes
- Les identifiants conviviaux s'écrivent tels que le modèle les porte, majuscules comprises. Un nom qui ne désigne rien dans le modèle est ignoré, sans erreur : relisez la réponse.
- Chaque participant « à définir » du modèle reçoit une personne ; sinon l'envoi est refusé : « Le parcours a encore un participant dynamique non associé à un contact ou un utilisateur : Client ». Un participant que le modèle fait remplacer par son créateur devient l'utilisateur authentifié.
- Le parcours naît dans l'organisation de l'utilisateur authentifié. Pour une organisation cliente, appelez avec un utilisateur de cette organisation.
- 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 code de signature par SMS.
- La requête entière, fichiers compris, est limitée à 1 Gio.
Le premier guide ci-dessous retrouve le modèle et ses identifiants conviviaux ; les suivants prennent chacun un changement. Ils se combinent : une même requête peut remplacer la personne, le document et un réglage.
Dans ce chapitre
-
Trouver un modèle et ses identifiants conviviaux
Lister les modèles de parcours, puis lire celui qui sert pour relever ses participants et ses documents.
-
Créer un parcours depuis un modèle, tel quel
Envoyer un parcours qui reprend son modèle sans rien y changer.
-
Remplacer un participant par un contact existant
Désigner, pour un participant du modèle, un contact ou un utilisateur déjà enregistré, par son identifiant.
-
Remplacer un participant par un nouveau contact
Donner, pour un participant du modèle, les coordonnées d'une personne qui n'est pas encore un contact — le contact est créé avec le parcours.
-
Remplacer un document par un fichier
Envoyer, à la place d'un document du modèle, le fichier de cet envoi — un PDF, une image ou un document Word.
-
Remplacer un document par un modèle de document
Faire signer, à la place d'un document du modèle, un document ou un modèle de document rédigé dans Docage, rempli des données du parcours.
-
Ajouter un participant au modèle — un nouveau contact
Faire signer, en plus des participants du modèle, une personne qui n'est pas encore un contact.
-
Ajouter un participant au modèle — un contact existant
Faire signer, en plus des participants du modèle, un contact ou un utilisateur déjà enregistré.
-
Ajouter un document au modèle
Faire signer, en plus des documents du modèle, un document propre à cet envoi.
-
Créer depuis un modèle, en brouillon
Créer le parcours sans l'envoyer, pour le vérifier ou le compléter, puis le lancer.
-
Modifier les réglages hérités du modèle
Changer, pour cet envoi seulement, le nom du parcours, sa durée de validité, ses relances ou son mode d'essai.
-
Changer le mode de signature d'un participant
Recevoir le code de signature par email plutôt que par SMS, ou changer un autre réglage d'un participant du modèle, pour cet envoi.
-
Renseigner les champs personnalisés du parcours
Donner, à la création, une valeur aux champs propres à votre organisation — un numéro de contrat, des options cochées.