Preparar un documento
Carga un PDF, asigna un firmante y coloca un campo con cURL o TypeScript, conservando el borrador.
Crea un contrato de prueba en estado de borrador. El mismo flujo sirve para conectar un proceso de tu aplicación con un documento de Digito: guardas el ID del sobre, revisas el PDF y distribuyes en una acción posterior.
Lo que necesitas
Una clave del equipo en DIGITO_API_TOKEN, un PDF local contrato.pdf y un destinatario sintético. Los ejemplos usan ana@example.com y crean el borrador; todavía no inician la distribución.
Define el PDF y la persona
Cada destinatario tiene email, name y role. Usa SIGNER para la persona que debe firmar. Los campos dentro del destinatario quedan asignados a esa persona.
El campo del ejemplo se coloca en la página 1: positionX: 10, positionY: 75, width: 30 y height: 8 son porcentajes de la página. identifier: 0 lo relaciona con el primer archivo multipart; el índice empieza en 0 y la página en 1.
Crea el borrador
La operación POST /envelope/create recibe multipart/form-data: payload contiene JSON y files contiene el PDF. No envíes un cuerpo JSON como sustituto del formulario.
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/create' \
-H "Authorization: $DIGITO_API_TOKEN" \
-F 'payload={
"type": "DOCUMENT",
"title": "Contrato de servicios de prueba",
"externalId": "contrato-prueba-001",
"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
}
]
}
],
"meta": {
"language": "es",
"timezone": "America/Santo_Domingo"
}
}' \
-F 'files=@./contrato.pdf;type=application/pdf'Guarda el bloque en preparar-documento.ts y ejecútalo en un servidor con Node.js que admita TypeScript. La comprobación de cabecera detecta un archivo equivocado; no sustituye la validación completa del PDF. Los 30 segundos son un tiempo de espera del ejemplo.
fetch y cURL generan el límite multipart. No fijes manualmente Content-Type: multipart/form-data.
Guarda el ID devuelto
La respuesta de creación tiene esta forma:
{
"id": "envelope_ejemplo"
}Relaciona id con el proceso de tu sistema. externalId permite buscar esa relación posteriormente; no es una clave de idempotencia ni impide duplicados por sí solo.
Si la conexión se interrumpe durante la creación, comprueba el resultado en Business antes de repetirla. Una espera agotada no prueba que la creación haya fallado.
Consulta y revisa el borrador
Sustituye el ID por el devuelto a tu integración:
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/envelope_ejemplo' \
-H "Authorization: $DIGITO_API_TOKEN"Comprueba type: "DOCUMENT", status: "DRAFT", un PDF en envelopeItems, el correo y rol del destinatario, y la relación de los campos con ambos IDs. Revisa visualmente el PDF en Business: unas coordenadas válidas no garantizan que el campo esté en el lugar deseado.
Errores habituales
| Problema | Corrección |
|---|---|
| La carga no se interpreta | Usa formulario multipart, payload en JSON y la parte files. |
| El campo aparece en otro documento | Comprueba el índice identifier y el orden de los PDFs enviados. |
| El campo queda fuera del área deseada | Revisa la página, los porcentajes y la vista del PDF. |
| Se crea más de un borrador | Reconcilia la creación tras una interrupción; no reintentes una escritura automáticamente. |
El paso de firma
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 del flujo no sustituyen esa autenticación. La rúbrica visible del campo representa la firma en el PDF; no es por sí sola la firma criptográfica.
Cuando el borrador esté revisado, continúa con distribuir, seguir y descargar. Para varios PDFs, consulta un sobre con varios documentos.