Senden Sie eine Dokumenten-Charge

Ein Batch fasst mehrere Dokumente zu einem einzigen Sendevorgang zusammen. Jedes Dokument kann an unterschiedliche Empfänger gehen und eine andere Vorlage verwenden. Sie steuern die Reihenfolge, in der die Dokumente gesendet werden, und ob Unterzeichner benachrichtigt werden, wenn frühere Dokumente im Batch abgeschlossen sind.

Das Unterschriftenerlebnis bei Batches unterscheidet sich ebenfalls von einer normalen Dokumentsendung. Unterzeichner sehen die anderen Dokumente im Batch als Teil ihres Signaturflusses, was ihnen eine Übersicht über die gesamte Dokumentenmenge gibt, die sie unterschreiben müssen. Wann und ob ein Unterzeichner jedes Dokument bearbeiten kann, wird weiterhin durch sequentialSigning (die Reihenfolge, in der Parteien innerhalb eines einzelnen Dokuments unterschreiben) und enforceOrder (die Reihenfolge, in der Dokumente innerhalb des Batches freigegeben werden) gesteuert. Siehe The four batching workflows für eine vollständige Aufschlüsselung, wie diese beiden Einstellungen kombiniert werden.

Der Prozess erfolgt in drei Schritten:

1. Erstellen Sie den Batch — erhalten Sie eine Batch-ID
2. Fügen Sie Dokumente zum Batch hinzu — eine Mutation pro Dokument
3. Starten Sie den Batch — löst das Senden aus

Voraussetzungen

• Ein Legalesign-Konto mit API-Zugang und Ihren Authentifizierungsdaten (siehe authenticate)
• Mindestens eine Vorlage mit konfigurierten Rollen und deren Vorlagen-ID
• Ihre Gruppen-ID

Schritt 1: Erstellen Sie den Batch

Rufen Sie sendBatch auf, um den Batch zu initialisieren und eine Batch-ID zu erhalten. Diese ID verwenden Sie in allen folgenden Aufrufen.

mutation CreateBatch {
  sendBatch(input: {
    batchName: "August contracts"
    groupId: "Z3JwWW91ckdyb3VwSWQ="
    enforceOrder: true
    notifySender: true
    notifySenderAttach: false
    notifyParticipants: true
    notifyParticipantsAttach: false
  })
}

Antwort:

{
  "data": {
    "sendBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

Speichern Sie die zurückgegebene ID — dies ist Ihre batchId für alle folgenden Aufrufe.

Wichtige Felder:

• enforceOrder: true — Dokumente werden in der Reihenfolge von sendOrder gesendet; das nächste Dokument wird erst gesendet, wenn das vorherige abgeschlossen ist
• notifySender / notifyParticipants — steuern E-Mail-Benachrichtigungen bei Abschluss
• notifySenderAttach / notifyParticipantsAttach — ob das unterschriebene PDF an diese Benachrichtigungen angehängt wird

Siehe SendBatchInput für alle Felder.

Schritt 2: Fügen Sie Dokumente zum Batch hinzu

Rufen Sie sendBatchDocument für jedes Dokument einmal auf. Verwenden Sie sendOrder zur Steuerung der Reihenfolge (0-basiert).

Erstes Dokument (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
        }
      ]
    }
  })
}

Antwort:

{
  "data": {
    "sendBatchDocument": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

Die Antwort gibt die batchId zurück — keine Dokument-ID.

Zweites Dokument (sendOrder: 1)

Wiederholen Sie die Mutation mit einer anderen Vorlage, sendOrder: 1 und gleichen oder anderen Empfängern:

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
        }
      ]
    }
  })
}

Fügen Sie so viele Dokumente wie nötig hinzu, bevor Sie zu Schritt 3 übergehen.

Tipp

Jedes Dokument kann eine andere Vorlage und andere Empfänger verwenden. Der Wert von sendOrder bestimmt die Reihenfolge, wenn enforceOrder auf true gesetzt ist.

Siehe SendBatchDocumentInput für alle Felder. Das verschachtelte document-Objekt folgt den gleichen Validierungsregeln wie DocumentSendSettingsInput.

Schritt 3: Starten Sie den Batch

Sobald alle Dokumente hinzugefügt wurden, rufen Sie startBatch auf, um den Batch als bereit zu markieren. Dies löst das Senden aus.

mutation StartBatch {
  startBatch(input: {
    batchId: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
    groupId: "Z3JwWW91ckdyb3VwSWQ="
  })
}

Antwort:

{
  "data": {
    "startBatch": "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw"
  }
}

Nach startBatch legt Legalesign die Dokumente in die Warteschlange. Wenn enforceOrder auf true ist, wird das erste Dokument (sendOrder: 0) sofort gesendet und nachfolgende Dokumente werden zurückgehalten, bis das vorherige abgeschlossen ist.

Verfolgen Sie den Batch-Fortschritt

Batches haben auch eine eigene Ansicht in der Legalesign Web-App, die Ihnen eine konsolidierte Übersicht über alle Dokumente im Batch und deren Unterschriftsstatus gibt — hilfreich, um den Fortschritt zu überwachen, ohne die API abzufragen.

Um den Status des Batches programmgesteuert abzufragen, verwenden Sie die Batch-ID:

query GetBatch {
  batch(id: "dHNrWW91ckJhdGNoSWQtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw") {
    id
    status
    documents {
      edges {
        node {
          id
          title
          status
        }
      }
    }
  }
}

Sie können auch Subscriptions verwenden, um Echtzeit-Updates zu erhalten — siehe Track Document and Recipient Lifecycle with Subscriptions.

Verwandte Themen

• sendBatch
• sendBatchDocument
• startBatch
• SendBatchInput
• SendBatchDocumentInput
• Batch type
• Troubleshoot Send Validation