Un sobre con varios documentos

Un sobre puede contener varios PDFs. Este ejemplo prepara contrato.pdf y anexo.pdf para una misma persona y conserva un único borrador con campos en ambos documentos.

Cómo se relacionan los archivos y los camposCopiar link al encabezado

Al crear el sobre, cada campo usa identifier para elegir un archivo del formulario. Después de la creación, la API devuelve envelopeItems[].id para cada PDF; las operaciones de campos y descarga utilizan ese ID.

El índice del archivo empieza en 0. La página empieza en 1 dentro de cada PDF. No uses identifier como sustituto de un envelopeItemId después de la creación.

Crea el borradorCopiar link al encabezado

Configura DIGITO_API_TOKEN en el servidor y prepara ambos PDFs con datos de prueba.

curl --fail-with-body \
  'https://business.digito.do/api/v2/envelope/create' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -F 'payload={
  "type": "DOCUMENT",
  "title": "Contrato y anexo de prueba",
  "externalId": "expediente-003",
  "recipients": [
    {
      "email": "ana@example.com",
      "name": "Ana Pérez",
      "role": "SIGNER",
      "fields": [
        {
          "identifier": 0,
          "type": "SIGNATURE",
          "page": 1,
          "positionX": 10,
          "positionY": 75,
          "width": 30,
          "height": 8
        },
        {
          "identifier": 1,
          "type": "SIGNATURE",
          "page": 1,
          "positionX": 10,
          "positionY": 80,
          "width": 30,
          "height": 8
        }
      ]
    }
  ],
  "meta": {
    "language": "es",
    "timezone": "America/Santo_Domingo"
  }
}' \
  -F 'files=@./contrato.pdf;type=application/pdf' \
  -F 'files=@./anexo.pdf;type=application/pdf'

La respuesta de creación devuelve solo el ID del sobre. Consulta GET /envelope/{envelopeId} para recuperar los PDFs, destinatarios y campos creados.

Comprueba las relacionesCopiar link al encabezado

Esta selección del detalle ilustra los IDs y el orden. El objeto completo contiene más propiedades:

{
  "id": "envelope_ejemplo",
  "status": "DRAFT",
  "envelopeItems": [
    {
      "id": "item_contrato",
      "title": "contrato.pdf",
      "order": 1
    },
    {
      "id": "item_anexo",
      "title": "anexo.pdf",
      "order": 2
    }
  ],
  "fields": [
    {
      "id": 501,
      "recipientId": 123,
      "envelopeItemId": "item_contrato",
      "type": "SIGNATURE",
      "page": 1
    },
    {
      "id": 502,
      "recipientId": 123,
      "envelopeItemId": "item_anexo",
      "type": "SIGNATURE",
      "page": 1
    }
  ]
}

Los valores son sintéticos: usa los IDs y órdenes realmente devueltos. Revisa cada PDF en Business y comprueba que cada campo pertenezca al elemento correcto. Al actualizar campos existentes, usa envelopeItemId, no el índice de la carga.

Distribución y archivo finalCopiar link al encabezado

La distribución se hace una vez para el sobre completo. Cuando status sea COMPLETED, descarga la versión signed de cada envelopeItems[].id; descargar solamente el primer elemento perdería parte del expediente.

El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. Compartir un sobre o varios documentos no permite reutilizar una sesión o un token como autorización de firma.

Distribuir y descargar todos los PDFs · Añadir o actualizar archivos.