Metodi di Invio

L'API di Legalesign offre diversi modi per inviare documenti da firmare. Ogni metodo è adatto a un caso d'uso diverso. Tutti i metodi sono asincroni — restituiscono un ID immediatamente e processano il documento in background.

Confronto Rapido

Metodo	Caso d'uso	Documenti	Chiamate API
send	Invia un documento a uno o più destinatari	1	1
sendBatch	Invia più documenti diversi come gruppo	Molti	3+ (create → add docs → start)
sendBulk	Invia lo stesso modello a molti destinatari diversi	Molti	3+ (start → queue docs → send)
createTask	Esegue attività asincrone come report	N/A	1

send — Documento Singolo

Il metodo più semplice e comune. Una chiamata API invia un documento a uno o più destinatari.

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

Quando usarlo: La maggior parte delle integrazioni. Invio di un contratto, NDA o qualsiasi documento singolo. Se devi inviare documenti uno alla volta dalla tua applicazione, questa è la scelta giusta.

Restituisce: Un ID attività. Fai polling con la query task e controlla task.report.status finché non raggiunge COMPLETATO o FALLITO.

Vedi: riferimento send · DocumentSendSettingsInput

sendBatch — Più Documenti come Gruppo

Invia più documenti diversi logicamente correlati (es. un pacchetto di assunzione con contratto, NDA, e conferma del manuale). I documenti sono raggruppati in un Batch e possono essere inviati in un ordine specifico.

Il flusso di lavoro richiede tre passaggi:

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

Quando usarlo: Per inviare più documenti correlati alla stessa persona o gruppo di persone. Il flag enforceOrder controlla se i documenti devono essere firmati in sequenza o possono essere firmati in qualsiasi ordine.

Vedi: sendBatch · sendBatchDocument · startBatch · tipo Batch

sendBulk — Stesso Modello a Molti Destinatari

Invia lo stesso modello a molti destinatari diversi in parallelo. Utile per spedizioni massive come rinnovi annuali di polizze o conferme di conformità.

Il flusso di lavoro:

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

Quando usarlo: Per inviare lo stesso documento a centinaia o migliaia di persone diverse. Più efficiente che chiamare send in un ciclo perché la piattaforma elabora la coda in parallelo.

Vedi: startBulk · addBulkDocument · sendBulk

createTask — Attività Asincrone

Non è un metodo di invio, ma è correlato. createTask avvia operazioni asincrone come la generazione di report. Il sistema di attività è lo stesso che alimenta send — entrambi restituiscono un ID attività su cui puoi fare polling.

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

Vedi: createTask · TaskStatus

Scegliere il Metodo Giusto

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 maggior parte delle integrazioni ha bisogno solo di send. Usa sendBatch e sendBulk quando hai un flusso di lavoro specifico che richiede raggruppamento o invii di massa.

Opzioni di Notifica

Sia sendBatch che sendBulk accettano flag di notifica che controllano il comportamento delle email:

Flag	Descrizione
enforceOrder	I documenti devono essere firmati nell'ordine sendOrder specificato
notifySender	Invia un'email al mittente quando ogni documento viene firmato
notifySenderAttach	Allegare il PDF firmato alla notifica al mittente
notifyParticipants	Invia un'email ai partecipanti quando il documento è completo
notifyParticipantsAttach	Allegare il PDF firmato alle notifiche dei partecipanti

La mutazione send eredita queste impostazioni dalla configurazione Experience del gruppo.