Méthodes d'envoi

L'API Legalesign propose plusieurs façons d'envoyer des documents pour signature. Chaque méthode convient à un cas d'utilisation différent. Toutes les méthodes sont asynchrones — elles renvoient immédiatement un ID et traitent le document en arrière-plan.

Comparaison rapide

Méthode	Cas d'utilisation	Documents	Appels API
send	Envoyer un document à un ou plusieurs destinataires	1	1
sendBatch	Envoyer plusieurs documents différents en groupe	Plusieurs	3+ (create → add docs → start)
sendBulk	Envoyer le même modèle à plusieurs destinataires différents	Plusieurs	3+ (start → queue docs → send)
createTask	Exécuter des tâches asynchrones comme des rapports	N/A	1

send — Document unique

La méthode la plus simple et la plus courante. Un appel API envoie un document à un ou plusieurs destinataires.

mutation {
  send(input: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract"
    recipients: [
      { firstName: "Jane", lastName: "Smith", email: "jane@example.com", role: "Signer" }
    ]
  })
}

Quand utiliser : La plupart des intégrations. Envoi d’un contrat, NDA, ou tout document unique. Si vous devez envoyer des documents un par un depuis votre application, c’est la méthode appropriée.

Retour : Un ID de tâche. Effectuez un polling avec la requête task et surveillez task.report.status jusqu’à ce qu’il atteigne COMPLETED ou FAILED.

Voir : send référence · DocumentSendSettingsInput

sendBatch — Plusieurs documents en groupe

Envoie plusieurs documents différents qui sont logiquement liés (ex. un pack d’embauche contenant un contrat, un NDA et un accusé de réception du manuel). Les documents sont regroupés dans un Batch et peuvent être envoyés dans un ordre spécifique.

Le workflow nécessite trois étapes :

# Step 1: Create the batch
mutation { sendBatch(input: { groupId: "Z3JwMTIzNDU2", batchName: "New Hire Pack" }) }
# Returns: batchId

# Step 2: Add documents to the batch (repeat for each document)
mutation { sendBatchDocument(input: {
  batchId: "<batchId>",
  sendOrder: 1,
  document: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract"
    recipients: [{ firstName: "Jane", lastName: "Smith", email: "jane@example.com", role: "Signer" }]
  }
}) }

# Step 3: Start the batch
mutation { startBatch(input: { batchId: "<batchId>", groupId: "Z3JwMTIzNDU2" }) }

Quand utiliser : Envoyer plusieurs documents liés à la même personne ou groupe de personnes. Le drapeau enforceOrder contrôle si les documents doivent être signés séquentiellement ou dans n’importe quel ordre.

Voir : sendBatch · sendBatchDocument · startBatch · Batch type

sendBulk — Même modèle à plusieurs destinataires

Envoie le même modèle à plusieurs destinataires différents en parallèle. Utile pour les mailings de masse comme les renouvellements annuels de politique ou les accusés de conformité.

Le workflow :

# Step 1: Create the bulk task
mutation { startBulk(input: { groupId: "Z3JwMTIzNDU2", name: "Annual Policy Renewal" }) }
# Returns: bulkId

# Step 2: Queue documents (repeat for each recipient)
mutation { addBulkDocument(input: {
  bulkId: "<bulkId>",
  document: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Policy Renewal - John Doe"
    recipients: [{ firstName: "John", lastName: "Doe", email: "john@example.com", role: "Signer" }]
  }
}) }

# Step 3: Send all queued documents
mutation { sendBulk(input: { groupId: "Z3JwMTIzNDU2", bulkId: "<bulkId>", name: "Annual Policy Renewal" }) }

Quand utiliser : Envoyer le même document à des centaines ou milliers de personnes différentes. Plus efficace que d’appeler send en boucle car la plateforme traite la file d’attente en parallèle.

Voir : startBulk · addBulkDocument · sendBulk

createTask — Tâches asynchrones

Ce n’est pas une méthode d’envoi, mais est liée. createTask déclenche des opérations asynchrones comme la génération de rapports. Le système de tâches est le même que celui utilisé par send — les deux renvoient un ID de tâche que vous pouvez interroger.

mutation {
  createTask(input: {
    groupId: "Z3JwMTIzNDU2"
    title: "Audit Report"
    status: DRAFT
  }) {
    id
    status
  }
}

Voir : createTask · TaskStatus

Choisir la bonne méthode

Need to send one document?
  → use send

Need to send multiple different documents as a package?
  → use sendBatch

Need to send the same template to many people?
  → use sendBulk

Just need one or two documents sent from your app?
  → use send (even if you call it multiple times)

La plupart des intégrations nécessitent uniquement send. Utilisez sendBatch et sendBulk lorsque vous avez un workflow spécifique qui requiert un regroupement ou un envoi massif.

Options de notification

Les méthodes sendBatch et sendBulk acceptent des indicateurs de notification qui contrôlent le comportement des emails :

Indicateur	Description
enforceOrder	Les documents doivent être signés dans l’ordre spécifié par sendOrder
notifySender	Envoyer un email à l’expéditeur à chaque signature de document
notifySenderAttach	Joindre le PDF signé à la notification envoyée à l’expéditeur
notifyParticipants	Envoyer un email aux participants lorsque le document est complet
notifyParticipantsAttach	Joindre le PDF signé aux notifications des participants

La mutation send hérite de ces réglages à partir de la configuration Experience du groupe.