Métodos de Envío

La API de Legalesign ofrece varias formas de enviar documentos para firma. Cada método se adapta a un caso de uso diferente. Todos los métodos son asíncronos: devuelven un ID inmediatamente y procesan el documento en segundo plano.

Comparación Rápida

Método	Caso de uso	Documentos	Llamadas API
send	Enviar un documento a uno o más destinatarios	1	1
sendBatch	Enviar múltiples documentos diferentes como un grupo	Muchos	3+ (crear → agregar docs → iniciar)
sendBulk	Enviar la misma plantilla a muchos destinatarios diferentes	Muchos	3+ (iniciar → encolar docs → enviar)
createTask	Ejecutar tareas asíncronas como informes	N/D	1

send — Documento Único

El método más sencillo y común. Una llamada API envía un documento a uno o más destinatarios.

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

Cuándo usarlo: La mayoría de las integraciones. Enviar un contrato, NDA o cualquier documento único. Si necesitas enviar documentos uno a la vez desde tu aplicación, esta es la opción adecuada.

Devuelve: Un ID de tarea. Consulta con la query task y monitorea task.report.status hasta que alcance COMPLETED o FAILED.

Consulta: referencia de send · DocumentSendSettingsInput

sendBatch — Múltiples Documentos como Grupo

Envía múltiples documentos diferentes que están lógicamente relacionados (p. ej., un paquete de empleo con contrato, NDA y acuse de recibo del manual). Los documentos se agrupan en un Batch y pueden enviarse en un orden específico.

El flujo de trabajo requiere tres pasos:

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

Cuándo usarlo: Enviar múltiples documentos relacionados a la misma persona o grupo de personas. La bandera enforceOrder controla si los documentos deben firmarse secuencialmente o pueden firmarse en cualquier orden.

Consulta: sendBatch · sendBatchDocument · startBatch · tipo Batch

sendBulk — Mismo Template a Muchos Destinatarios

Envía la misma plantilla a muchos destinatarios diferentes en paralelo. Útil para envíos masivos como renovaciones anuales de políticas o reconocimientos de cumplimiento.

El flujo de trabajo:

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

Cuándo usarlo: Enviar el mismo documento a cientos o miles de personas diferentes. Más eficiente que llamar a send en un bucle porque la plataforma procesa la cola en paralelo.

Consulta: startBulk · addBulkDocument · sendBulk

createTask — Tareas Asíncronas

No es un método de envío, pero está relacionado. createTask dispara operaciones asíncronas como generar informes. El sistema de tareas es el mismo que impulsa send: ambos devuelven un ID de tarea que puedes consultar.

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

Consulta: createTask · TaskStatus

Elegir el Método Correcto

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 mayoría de las integraciones solo necesitan send. Usa sendBatch y sendBulk cuando tengas un flujo de trabajo específico que requiera agrupación o envío masivo.

Opciones de Notificación

Tanto sendBatch como sendBulk aceptan banderas de notificación que controlan el comportamiento del correo electrónico:

Bandera	Descripción
enforceOrder	Los documentos deben firmarse en el sendOrder especificado
notifySender	Enviar correo al remitente cuando se firme cada documento
notifySenderAttach	Adjuntar el PDF firmado a la notificación del remitente
notifyParticipants	Enviar correo a los participantes cuando el documento esté completo
notifyParticipantsAttach	Adjuntar el PDF firmado a las notificaciones a los participantes

La mutación send hereda estos ajustes desde la configuración del Experience del grupo.