Versandmethoden

Die Legalesign API bietet mehrere Möglichkeiten, Dokumente zum Unterschreiben zu versenden. Jede Methode eignet sich für einen anderen Anwendungsfall. Alle Methoden sind asynchron – sie geben sofort eine ID zurück und verarbeiten das Dokument im Hintergrund.

Kurzer Vergleich

Methode	Anwendungsfall	Dokumente	API-Aufrufe
send	Ein Dokument an einen oder mehrere Empfänger senden	1	1
sendBatch	Mehrere verschiedene Dokumente als Gruppe senden	Viele	3+ (erstellen → Dokumente hinzufügen → starten)
sendBulk	Dieselbe Vorlage an viele verschiedene Empfänger senden	Viele	3+ (starten → Dokumente in Warteschlange → senden)
createTask	Asynchrone Aufgaben wie Berichte ausführen	N/A	1

send — Einzeldokument

Die einfachste und häufigste Methode. Ein API-Aufruf sendet ein Dokument an einen oder mehrere Empfänger.

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

Wann verwenden: Die meisten Integrationen. Senden eines Vertrags, einer Geheimhaltungsvereinbarung (NDA) oder eines einzelnen Dokuments. Wenn Sie Dokumente einzeln aus Ihrer Anwendung versenden müssen, ist dies die richtige Wahl.

Rückgabe: Eine Task-ID. Abfragen mit der task Query und Überwachung von task.report.status, bis dieser COMPLETED oder FAILED erreicht.

Siehe: send Referenz · DocumentSendSettingsInput

sendBatch — Mehrere Dokumente als Gruppe

Sendet mehrere verschiedene Dokumente, die logisch zusammengehören (z. B. ein Beschäftigungspaket mit Vertrag, NDA und Handbuchbestätigung). Die Dokumente werden in einem Batch gruppiert und können in einer bestimmten Reihenfolge versendet werden.

Der Ablauf erfordert drei Schritte:

# 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" }) }

Wann verwenden: Versand mehrerer verwandter Dokumente an dieselbe Person oder Gruppe. Das enforceOrder-Flag steuert, ob Dokumente nacheinander oder beliebig unterschrieben werden müssen.

Siehe: sendBatch · sendBatchDocument · startBatch · Batch Typ

sendBulk — Dieselbe Vorlage an viele Empfänger

Sendet dieselbe Vorlage parallel an viele verschiedene Empfänger. Nützlich für Massenversand wie jährliche Policenerneuerungen oder Compliance-Bestätigungen.

Der Ablauf:

# 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" }) }

Wann verwenden: Versand desselben Dokuments an hunderte oder tausende verschiedene Personen. Effizienter als das Aufrufen von send in einer Schleife, da die Plattform die Warteschlange parallel verarbeitet.

Siehe: startBulk · addBulkDocument · sendBulk

createTask — Asynchrone Aufgaben

Keine Versandmethode, aber verwandt. createTask startet asynchrone Operationen wie das Erstellen von Berichten. Das Task-System ist dasselbe, das auch send antreibt – beide geben eine Task-ID zurück, die abgefragt werden kann.

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

Siehe: createTask · TaskStatus

Die richtige Methode wählen

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)

Die meisten Integrationen benötigen nur send. Verwenden Sie sendBatch und sendBulk, wenn Sie einen spezifischen Workflow haben, der Gruppierung oder Massenversand erfordert.

Benachrichtigungsoptionen

Sowohl sendBatch als auch sendBulk akzeptieren Benachrichtigungs-Flags, die das Verhalten von E-Mails steuern:

Flag	Beschreibung
enforceOrder	Dokumente müssen in der angegebenen sendOrder unterschrieben werden
notifySender	E-Mail an den Absender, wenn jedes Dokument unterschrieben wurde
notifySenderAttach	Fügen Sie die unterschriebene PDF der Absenderbenachrichtigung bei
notifyParticipants	E-Mail an Teilnehmer, wenn das Dokument abgeschlossen ist
notifyParticipantsAttach	Fügen Sie die unterschriebene PDF den Teilnehmerbenachrichtigungen bei

Die Mutation send erbt diese Einstellungen von der Experience Konfiguration der Gruppe.