Destinatarios y funciones

Los destinatarios son personas con una función dentro del sobre. Su id es numérico y relaciona a cada participante con sus campos. Un destinatario no es un usuario de tu integración ni una clave de API.

Configura los roles que corresponden a tu proceso y revisa el comportamiento antes de distribuir. La presencia de un rol en el contrato no concede permisos adicionales al servidor de tu aplicación.

Añade participantes a un borradorCopiar link al encabezado

Puedes definir destinatarios dentro de /envelope/create o añadirlos después con /envelope/recipient/create-many. Este ejemplo añade un firmante y una copia a un borrador existente. No ejecutes ambas vías para la misma persona.

curl --fail-with-body \
  'https://business.digito.do/api/v2/envelope/recipient/create-many' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
  "envelopeId": "envelope_ejemplo",
  "data": [
    {
      "email": "ana@example.com",
      "name": "Ana Pérez",
      "role": "SIGNER",
      "signingOrder": 1
    },
    {
      "email": "copia@example.com",
      "name": "Archivo",
      "role": "CC"
    }
  ]
}'

La respuesta agrupa los destinatarios creados en data. Guarda el id de cada persona; no uses su posición en el array como ID. Consulta el contrato completo antes de configurar opciones adicionales.

Prepara un orden secuencialCopiar link al encabezado

Para que los destinatarios actúen en secuencia, configura meta.signingOrder: "SEQUENTIAL" en el sobre y signingOrder numérico en cada destinatario. Para un flujo en paralelo, usa PARALLEL en los metadatos del sobre.

{
  "envelopeId": "envelope_ejemplo",
  "meta": {
    "signingOrder": "SEQUENTIAL"
  }
}

Este cuerpo corresponde a POST /envelope/update. Después, asigna el orden a los IDs reales y corrige los datos que necesite el borrador:

curl --fail-with-body \
  'https://business.digito.do/api/v2/envelope/recipient/update-many' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
  "envelopeId": "envelope_ejemplo",
  "data": [
    {
      "id": 123,
      "name": "Ana Pérez",
      "signingOrder": 1
    },
    {
      "id": 124,
      "signingOrder": 2
    }
  ]
}'

Estas son dos operaciones separadas, no una transacción. Si falla la segunda, consulta el estado del borrador antes de continuar. Verifica el orden en la revisión del documento antes de distribuir.

Interpreta el progresoCopiar link al encabezado

Obtén un destinatario con GET /envelope/recipient/{recipientId} o consulta recipients en el sobre. Esta selección muestra campos de progreso de un destinatario sintético:

{
  "id": 123,
  "email": "ana@example.com",
  "role": "SIGNER",
  "sendStatus": "SENT",
  "readStatus": "OPENED",
  "signingStatus": "NOT_SIGNED",
  "signedAt": null,
  "rejectionReason": null
}

El objeto completo contiene más propiedades. SENT y OPENED no significan que la persona haya firmado. Comprueba signingStatus y el estado general del sobre; signedAt, rejectionReason, expiresAt y expired ayudan a interpretar el resultado.

Autenticación de la personaCopiar link al encabezado

El token del destinatario es sensible. No lo registres, no lo publiques y entrégalo únicamente a la persona autorizada. La URL del flujo debe proceder de la aplicación o de una respuesta que la incluya; no la construyas a partir de un token.

El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. La sesión en Business, la clave de API y los tokens de destinatario o integración no sustituyen esta autenticación. La integración prepara y sigue el proceso; la persona autoriza su firma.

Añadir campos al destinatario · Consultar un destinatario.