Crear un documento desde una plantilla
Crea un sobre de documento a partir de un sobre de plantilla. Puedes reemplazar sus archivos mediante identificadores de elementos.
POST
/envelope/useURL base: https://business.digito.do/api/v2.
Ejemplos
Configura DIGITO_API_TOKEN en el servidor. Sustituye los IDs y archivos de ejemplo por los de tu equipo. TypeScript usa fetch y FormData de Node.js.
curl --fail-with-body \
--request POST \
--url 'https://business.digito.do/api/v2/envelope/use' \
--header "Authorization: $DIGITO_API_TOKEN" \
--form 'payload={
"envelopeId": "plantilla_de_ejemplo",
"recipients": [
{
"id": 501,
"email": "ana@example.com",
"name": "Ana Ejemplo"
}
],
"distributeDocument": false,
"override": {
"title": "Contrato de Ana Ejemplo",
"language": "es"
}
}'Antes de empezar
- Usa el identificador del sobre de tipo
TEMPLATE. Los destinatarios pueden completarse con los identificadores de la plantilla.distributeDocumentdistribuye el documento creado cuando se solicita; omítelo al preparar un borrador.
Autenticación
Envía el token de la API en el encabezado Authorization. El acceso corresponde al equipo y a los permisos del token. Conserva el token en tu servidor.
Authorization: api_TU_TOKENAntes de cada acción de firma, el firmante debe autenticarse de nuevo con Digito ID. Una sesión previa de Business, un token de destinatario o un token de la API no sustituye este requisito.
Parámetros
Esta operación no declara parámetros de ruta ni de consulta.
Cuerpo de la solicitud
El cuerpo es obligatorio.
Tipo de contenido: multipart/form-data.
Objeto payload
Envía este objeto como texto JSON en la parte payload del formulario.
{
"envelopeId": "plantilla_de_ejemplo",
"recipients": [
{
"id": 501,
"email": "ana@example.com",
"name": "Ana Ejemplo"
}
],
"distributeDocument": false,
"override": {
"title": "Contrato de Ana Ejemplo",
"language": "es"
}
}Este ejemplo reutiliza los archivos de la plantilla y no incluye una parte files. Para reemplazar archivos, consulta customDocumentData y relaciona cada archivo con su elemento de la plantilla.
Los valores muestran una solicitud posible; no son valores predeterminados del servidor.
| Propiedad | Tipo | Obligatoria | Restricciones |
|---|---|---|---|
payload | object | Sí | Sin restricciones adicionales en este nivel. |
files | array de estructura no especificada | No | Sin restricciones adicionales en este nivel. |
Propiedades de payload
| Propiedad | Tipo | Obligatoria | Restricciones |
|---|---|---|---|
envelopeId | string | Sí | Sin restricciones adicionales en este nivel. |
externalId | string | No | Sin restricciones adicionales en este nivel. |
recipients | array de object | No | Sin restricciones adicionales en este nivel. |
distributeDocument | boolean | No | Sin restricciones adicionales en este nivel. |
customDocumentData | array de object | No | Sin restricciones adicionales en este nivel. |
folderId | string | No | Sin restricciones adicionales en este nivel. |
prefillFields | array de combinación (allOf) | No | Sin restricciones adicionales en este nivel. |
override | object | No | Sin restricciones adicionales en este nivel. |
attachments | array de object | No | Sin restricciones adicionales en este nivel. |
formValues | object | No | Sin restricciones adicionales en este nivel. |
Ver el esquema completo de la solicitud
{
"type": "object",
"properties": {
"payload": {
"type": "object",
"properties": {
"envelopeId": {
"type": "string"
},
"externalId": {
"type": "string"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"email": {
"anyOf": [
{
"type": "string",
"enum": [
""
]
},
{
"type": "string",
"pattern": "^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~\\u{0080}-\\u{FFFF}-]+@[a-zA-Z0-9\\u{0080}-\\u{FFFF}](?:[a-zA-Z0-9\\u{0080}-\\u{FFFF}-]{0,61}[a-zA-Z0-9\\u{0080}-\\u{FFFF}])?(?:\\.[a-zA-Z0-9\\u{0080}-\\u{FFFF}](?:[a-zA-Z0-9\\u{0080}-\\u{FFFF}-]{0,61}[a-zA-Z0-9\\u{0080}-\\u{FFFF}])?)*$",
"maxLength": 254
}
]
},
"name": {
"type": "string",
"maxLength": 255
},
"signingOrder": {
"type": "number"
}
},
"required": [
"id",
"email"
]
}
},
"distributeDocument": {
"type": "boolean"
},
"customDocumentData": {
"type": "array",
"items": {
"type": "object",
"properties": {
"identifier": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"envelopeItemId": {
"type": "string"
}
},
"required": [
"identifier",
"envelopeItemId"
]
}
},
"folderId": {
"type": "string"
},
"prefillFields": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "number"
}
},
"required": [
"id"
]
},
{
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
},
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"radio"
]
},
"label": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"checkbox"
]
},
"label": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"dropdown"
]
},
"label": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"date"
]
},
"value": {
"type": "string"
}
},
"required": [
"type"
]
}
]
}
]
}
},
"override": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"subject": {
"type": "string",
"maxLength": 254
},
"message": {
"type": "string",
"maxLength": 5000
},
"timezone": {
"type": "string"
},
"dateFormat": {
"type": "string",
"enum": [
"yyyy-MM-dd hh:mm a",
"yyyy-MM-dd",
"dd/MM/yyyy",
"dd-MM-yyyy",
"MM/dd/yyyy",
"yy-MM-dd",
"MMMM dd, yyyy",
"EEEE, MMMM dd, yyyy",
"dd/MM/yyyy hh:mm a",
"dd/MM/yyyy HH:mm",
"dd-MM-yyyy hh:mm a",
"dd-MM-yyyy HH:mm",
"MM/dd/yyyy hh:mm a",
"MM/dd/yyyy HH:mm",
"dd.MM.yyyy",
"dd.MM.yyyy HH:mm",
"yyyy-MM-dd HH:mm",
"yy-MM-dd hh:mm a",
"yy-MM-dd HH:mm",
"yyyy-MM-dd HH:mm:ss",
"MMMM dd, yyyy hh:mm a",
"MMMM dd, yyyy HH:mm",
"EEEE, MMMM dd, yyyy hh:mm a",
"EEEE, MMMM dd, yyyy HH:mm",
"yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
]
},
"redirectUrl": {
"type": "string"
},
"distributionMethod": {
"type": "string",
"enum": [
"EMAIL",
"NONE"
]
},
"emailSettings": {
"type": "object",
"properties": {
"recipientSigningRequest": {
"type": "boolean",
"default": true
},
"recipientRemoved": {
"type": "boolean",
"default": true
},
"recipientSigned": {
"type": "boolean",
"default": true
},
"documentPending": {
"type": "boolean",
"default": true
},
"documentCompleted": {
"type": "boolean",
"default": true
},
"documentDeleted": {
"type": "boolean",
"default": true
},
"ownerDocumentCompleted": {
"type": "boolean",
"default": true
},
"ownerRecipientExpired": {
"type": "boolean",
"default": true
},
"ownerDocumentCreated": {
"type": "boolean",
"default": true
}
},
"default": {
"recipientSigningRequest": true,
"recipientRemoved": true,
"recipientSigned": true,
"documentPending": true,
"documentCompleted": true,
"documentDeleted": true,
"ownerDocumentCompleted": true,
"ownerRecipientExpired": true,
"ownerDocumentCreated": true
}
},
"language": {
"type": "string",
"enum": [
"en",
"es"
]
},
"typedSignatureEnabled": {
"type": "boolean"
},
"uploadSignatureEnabled": {
"type": "boolean"
},
"drawSignatureEnabled": {
"type": "boolean"
},
"allowDictateNextSigner": {
"type": "boolean"
},
"envelopeExpirationPeriod": {
"nullable": true,
"anyOf": [
{
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"amount": {
"type": "integer",
"minimum": 1
}
},
"required": [
"unit",
"amount"
]
},
{
"type": "object",
"properties": {
"disabled": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"disabled"
]
}
]
}
}
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"data": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"enum": [
"link"
],
"default": "link"
}
},
"required": [
"label",
"data"
]
}
},
"formValues": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "number"
}
]
}
}
},
"required": [
"envelopeId"
]
},
"files": {
"type": "array",
"items": {}
}
},
"required": [
"payload"
]
}Respuesta de éxito
signingUrl representa la URL que devuelve la API. Usa ese valor directamente; no construyas una ruta a partir del token. El marcador del ejemplo no es un link de firma.
Este objeto sintético ilustra la estructura completa de una respuesta 200. Los identificadores, fechas, estados y tokens son datos de ejemplo.
{
"id": "sobre_de_ejemplo",
"recipients": [
{
"id": 501,
"name": "Ana Ejemplo",
"email": "ana@example.com",
"token": "token_de_destinatario_ejemplo",
"role": "SIGNER",
"signingOrder": null,
"signingUrl": "URL_DE_FIRMA_DEVUELTA_POR_LA_API"
}
]
}Respuestas y errores
| Estado | Descripción | Contenido y esquema |
|---|---|---|
200 | Respuesta correcta. | application/json |
400 | Datos de entrada inválidos. | application/json |
401 | No se proporcionó autorización. | application/json |
403 | Permisos insuficientes. | application/json |
500 | Error interno del servidor. | application/json |
Los esquemas enlazados incluyen propiedades anidadas, campos obligatorios, variantes, enumeraciones, nulabilidad y restricciones. Consulta errores y reintentos para manejar respuestas no exitosas.
Identificador de operación: envelope-use.