Crear un documento desde una plantilla
Identifica destinatarios y campos reutilizables, rellena sus datos y crea un borrador independiente.
Usa una plantilla cuando el mismo PDF y la misma distribución de campos sirven para varios procesos. Cada uso produce un sobre nuevo de tipo DOCUMENT; la plantilla conserva su configuración para el siguiente uso.
Antes de empezar
Necesitas una clave del equipo y una plantilla preparada en Business con un destinatario SIGNER y un campo de texto. El ejemplo asigna una persona y precompleta una referencia de contrato sin distribuir el documento.
Encuentra la plantilla
Lista sobres de tipo TEMPLATE y obtiene el detalle del elegido:
curl --fail-with-body --get \
'https://business.digito.do/api/v2/envelope' \
-H "Authorization: $DIGITO_API_TOKEN" \
--data-urlencode 'type=TEMPLATE' \
--data-urlencode 'perPage=20'
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/envelope_plantilla_ejemplo' \
-H "Authorization: $DIGITO_API_TOKEN"Estos IDs pertenecen a la plantilla. Por ejemplo, una selección del detalle puede mostrar:
{
"id": "envelope_plantilla_ejemplo",
"type": "TEMPLATE",
"recipients": [
{
"id": 123,
"role": "SIGNER"
}
],
"fields": [
{
"id": 456,
"type": "TEXT",
"recipientId": 123
}
]
}Es una selección de propiedades, no una respuesta completa. Si tu plantilla tiene varios firmantes o campos de texto, usa los IDs configurados para cada función de tu proceso; no elijas el primero por posición.
Crea el documento con sus datos
POST /envelope/use recibe multipart aunque no sustituyas PDFs. Asocia recipients[].id y prefillFields[].id a los IDs de la plantilla. La variante para precompletar texto usa type: "text", en minúsculas.
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/use' \
-H "Authorization: $DIGITO_API_TOKEN" \
-F 'payload={
"envelopeId": "envelope_plantilla_ejemplo",
"externalId": "contrato-002",
"distributeDocument": false,
"recipients": [
{
"id": 123,
"email": "ana@example.com",
"name": "Ana Pérez"
}
],
"prefillFields": [
{
"id": 456,
"type": "text",
"value": "Contrato 002"
}
],
"override": {
"title": "Contrato de Ana Pérez",
"language": "es",
"timezone": "America/Santo_Domingo"
}
}'La respuesta devuelve id y recipients del documento nuevo. Guarda el nuevo id; no distribuyas ni descargues usando el ID de la plantilla. Los objetos de destinatario pueden contener tokens y URLs privadas: conserva esos datos solo cuando tu flujo los necesite y evita registrarlos completos.
Revisa el nuevo borrador
Consulta GET /envelope/{envelopeId} con el ID creado. Verifica destinatarios, valores, archivos y campos en el documento nuevo. Sus IDs pueden diferir de los de la plantilla.
distributeDocument: false separa la preparación de la distribución. Tras revisar el borrador, continúa con distribuir y descargar.
Sustituir un PDF de la plantilla
customDocumentData relaciona el archivo de sustitución con un envelopeItems[].id de la plantilla. Envía la parte files en el mismo formulario:
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/use' \
-H "Authorization: $DIGITO_API_TOKEN" \
-F 'payload={
"envelopeId": "envelope_plantilla_ejemplo",
"distributeDocument": false,
"recipients": [
{
"id": 123,
"email": "ana@example.com",
"name": "Ana Pérez"
}
],
"customDocumentData": [
{
"identifier": 0,
"envelopeItemId": "item_plantilla_ejemplo"
}
]
}' \
-F 'files=@./contrato-personalizado.pdf;type=application/pdf'identifier: 0 es el primer archivo enviado. El envelopeItemId corresponde al PDF que reemplazas en la plantilla. Comprueba que el PDF nuevo conserve las páginas y espacios necesarios para los campos; reemplazar el archivo no recoloca automáticamente tu diseño.
Diagnóstico
| Situación | Revisión |
|---|---|
| No se asigna la persona esperada | Revisa el ID del destinatario de la plantilla y su rol. |
| No cambia el texto | Usa el ID del campo original y la variante type: "text". |
| La plantilla no es accesible | Comprueba el equipo de la clave y type: "TEMPLATE". |
| El campo queda mal situado tras reemplazar el PDF | Revisa las páginas y coordenadas del archivo nuevo antes de distribuir. |
El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. La clave de API, una sesión abierta, el token del destinatario y los tokens de integración no sustituyen esa autenticación.