Envoyer un lot de documents
Un batch regroupe plusieurs documents en une seule opération d'envoi. Chaque document peut être destiné à différents destinataires et utiliser un modèle différent. Vous contrôlez l'ordre dans lequel les documents sont envoyés et si les signataires sont notifiés lorsque les documents précédents dans le lot sont complétés.
L'expérience de signature pour les lots est également différente d'un envoi de document standard. Les signataires voient les autres documents du lot dans leur flux de signature, ce qui leur donne une visibilité sur l'ensemble des documents qu'ils doivent signer. Le moment et la possibilité pour un signataire d'agir sur chaque document sont toujours contrôlés par sequentialSigning (l'ordre dans lequel les parties signent un même document) et enforceOrder (l'ordre dans lequel les documents sont libérés au sein du lot). Voir The four batching workflows pour une explication complète de la façon dont ces deux paramètres se combinent.
Le processus comprend trois étapes :
- Créer le lot — obtenir un ID de lot
- Ajouter des documents au lot — une mutation par document
- Démarrer le lot — déclenche l'envoi
Prerequisites
- Un compte Legalesign avec accès API et vos identifiants d'authentification (voir authenticate)
- Au moins un modèle avec des rôles configurés, et son ID de modèle
- Votre ID de groupe
Step 1: Create the Batch
Appelez sendBatch pour initialiser le lot et recevoir un ID de lot. Vous utiliserez cet ID à chaque appel ultérieur.
mutation CreateBatch {
sendBatch(input: {
batchName: "August contracts"
groupId: "Z3JwWW91ckdyb3VwSWQ="
enforceOrder: true
notifySender: true
notifySenderAttach: false
notifyParticipants: true
notifyParticipantsAttach: false
})
}
Response:
{
"data": {
"sendBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
}
}
Enregistrez l'ID retourné — c'est votre batchId pour tous les appels suivants.
Champs clés :
enforceOrder: true— les documents sont envoyés dans la séquencesendOrder; le document suivant est envoyé uniquement après la complétion du précédentnotifySender/notifyParticipants— contrôle les notifications par e-mail à la complétionnotifySenderAttach/notifyParticipantsAttach— indique si le PDF signé est joint à ces notifications
Voir SendBatchInput pour tous les champs.
Step 2: Add Documents to the Batch
Appelez sendBatchDocument une fois par document. Utilisez sendOrder pour contrôler la séquence (indexée à partir de 0).
First document (sendOrder: 0)
mutation AddDocumentToBatch {
sendBatchDocument(input: {
batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
sendOrder: 0
document: {
title: "Service Agreement"
templateId: "dHBsWW91clRlbXBsYXRlSWQtMDAwMC0wMDAwLTAwMDA="
groupId: "Z3JwWW91ckdyb3VwSWQ="
tag: ""
pdfPassword: ""
retainPdfPassword: false
allowPrinting: true
allowCopying: true
sequentialSigning: true
documentCCEmail: []
senderFields: [
{ id: "ZWxlWW91clNlbmRlckZpZWxkSWQ=", value: "Acme Ltd" }
]
participantFields: [
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZDE=", value: "" }
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZDI=", value: "" }
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZDM=", value: "" }
]
recipients: [
{
order: 0
signerIndex: 1
roleId: "cm9sWW91clJvbGVJZA=="
experience: "ZXhwWW91ckV4cGVyaWVuY2VJZA=="
firstName: "Alex"
lastName: "Taylor"
email: "alex.taylor@example.com"
phoneNumber: ""
expiryDate: null
timeZone: "Europe/London"
skipped: false
}
]
}
})
}
Response:
{
"data": {
"sendBatchDocument": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
}
}
La réponse renvoie le batchId — pas un ID de document.
Second document (sendOrder: 1)
Répétez la mutation avec un modèle différent, sendOrder: 1, et les mêmes ou différents destinataires :
mutation AddDocumentToBatch {
sendBatchDocument(input: {
batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
sendOrder: 1
document: {
title: "Data Processing Agreement"
templateId: "dHBsWW91clNlY29uZFRlbXBsYXRlSWQ="
groupId: "Z3JwWW91ckdyb3VwSWQ="
tag: ""
pdfPassword: ""
retainPdfPassword: false
allowPrinting: true
allowCopying: true
sequentialSigning: true
documentCCEmail: []
senderFields: [
{ id: "ZWxlU2VuZGVyRmllbGRBMQ==", value: "" }
{ id: "ZWxlU2VuZGVyRmllbGRBMg==", value: "Acme Ltd" }
]
participantFields: [
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZEEx", value: "" }
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZEEy", value: "" }
{ id: "ZWxlUGFydGljaXBhbnRGaWVsZEEz", value: "" }
]
recipients: [
{
order: 0
signerIndex: 1
roleId: "cm9sU2Vjb25kUm9sZUlk"
experience: "ZXhwWW91ckV4cGVyaWVuY2VJZA=="
firstName: "Alex"
lastName: "Taylor"
email: "alex.taylor@example.com"
phoneNumber: ""
expiryDate: null
timeZone: "Europe/London"
skipped: false
}
]
}
})
}
Ajoutez autant de documents que nécessaire avant de passer à l'Étape 3.
Chaque document peut utiliser un modèle et des destinataires différents. La valeur sendOrder détermine la séquence quand enforceOrder est true.
Voir SendBatchDocumentInput pour tous les champs. L'objet imbriqué document suit les mêmes règles de validation que DocumentSendSettingsInput.
Step 3: Start the Batch
Une fois tous les documents ajoutés, appelez startBatch pour marquer le lot prêt. Cela déclenche l'envoi.
mutation StartBatch {
startBatch(input: {
batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
groupId: "Z3JwWW91ckdyb3VwSWQ="
})
}
Response:
{
"data": {
"startBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
}
}
Après startBatch, Legalesign met les documents en file d'attente. Si enforceOrder est true, le premier document (sendOrder: 0) est envoyé immédiatement et les documents suivants sont retenus jusqu'à la complétion du précédent.
Tracking Batch Progress
Les lots disposent également de leur propre vue dédiée dans l'application web Legalesign, vous offrant un aperçu consolidé de tous les documents du lot et de leur état de signature — utile pour suivre l'avancement sans interroger l'API.
Pour interroger le statut d'un lot de façon programmatique, utilisez l'ID du lot :
query GetBatch {
batch(id: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw") {
id
status
documents {
edges {
node {
id
title
status
}
}
}
}
}
Vous pouvez également utiliser les abonnements pour recevoir des mises à jour en temps réel — voir Track Document and Recipient Lifecycle with Subscriptions.