Crear un sobre
Crea un sobre de documento o plantilla mediante una solicitud multipart.
POST
/envelope/createURL 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/create' \
--header "Authorization: $DIGITO_API_TOKEN" \
--form 'payload={
"title": "Contrato de servicios",
"type": "DOCUMENT",
"externalId": "contrato-2026-001",
"recipients": [
{
"email": "ana@example.com",
"name": "Ana Ejemplo",
"role": "SIGNER",
"signingOrder": 1
}
],
"meta": {
"language": "es"
}
}' \
--form 'files=@./documento.pdf;type=application/pdf'Antes de empezar
typedistingueDOCUMENTyTEMPLATE. El ejemplo usa un archivo PDF sintético y crea un borrador; la distribución se realiza con su operación específica.
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.
{
"title": "Contrato de servicios",
"type": "DOCUMENT",
"externalId": "contrato-2026-001",
"recipients": [
{
"email": "ana@example.com",
"name": "Ana Ejemplo",
"role": "SIGNER",
"signingOrder": 1
}
],
"meta": {
"language": "es"
}
}Añade el PDF en una parte files. Para varios archivos, repite esa parte. Deja que el cliente HTTP construya el límite multipart; no fijes manualmente Content-Type.
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 |
|---|---|---|---|
title | string | Sí | Longitud mínima: 1. Longitud máxima: 255 |
type | string | Sí | Valores: "DOCUMENT", "TEMPLATE" |
delegatedDocumentOwner | string | No | Patrón en el contrato completo |
externalId | string | No | Longitud máxima: 255 |
visibility | string | No | Valores: "EVERYONE", "MANAGER_AND_ABOVE", "ADMIN" |
globalAccessAuth | array de string | No | Sin restricciones adicionales en este nivel. |
globalActionAuth | array de string | No | Sin restricciones adicionales en este nivel. |
formValues | object | No | Sin restricciones adicionales en este nivel. |
folderId | string | No | Sin restricciones adicionales en este nivel. |
recipients | array de object | No | Sin restricciones adicionales en este nivel. |
meta | object | No | Sin restricciones adicionales en este nivel. |
attachments | array de object | No | Sin restricciones adicionales en este nivel. |
Ver el esquema completo de la solicitud
{
"type": "object",
"properties": {
"payload": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"type": {
"type": "string",
"enum": [
"DOCUMENT",
"TEMPLATE"
]
},
"delegatedDocumentOwner": {
"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}])?)*$"
},
"externalId": {
"type": "string",
"maxLength": 255
},
"visibility": {
"type": "string",
"enum": [
"EVERYONE",
"MANAGER_AND_ABOVE",
"ADMIN"
]
},
"globalAccessAuth": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ACCOUNT",
"TWO_FACTOR_AUTH"
]
}
},
"globalActionAuth": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ACCOUNT",
"PASSKEY",
"TWO_FACTOR_AUTH",
"PASSWORD"
]
}
},
"formValues": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "number"
}
]
}
},
"folderId": {
"type": "string"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"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
},
"role": {
"type": "string",
"enum": [
"CC",
"SIGNER",
"VIEWER",
"APPROVER",
"ASSISTANT"
]
},
"signingOrder": {
"type": "number"
},
"accessAuth": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ACCOUNT",
"TWO_FACTOR_AUTH"
]
},
"default": []
},
"actionAuth": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ACCOUNT",
"PASSKEY",
"TWO_FACTOR_AUTH",
"PASSWORD",
"EXPLICIT_NONE"
]
},
"default": []
},
"fields": {
"type": "array",
"items": {
"allOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"SIGNATURE"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
],
"default": "auto"
},
"type": {
"type": "string",
"enum": [
"signature"
]
}
},
"required": [
"type"
],
"default": {
"type": "signature",
"fontSize": 18,
"overflow": "auto"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"FREE_SIGNATURE"
]
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"INITIALS"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"initials"
]
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
}
},
"required": [
"type"
],
"default": {
"type": "initials",
"fontSize": 12,
"textAlign": "left"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"NAME"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"name"
]
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
}
},
"required": [
"type"
],
"default": {
"type": "name",
"fontSize": 12,
"textAlign": "left"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"EMAIL"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
],
"default": "auto"
},
"type": {
"type": "string",
"enum": [
"email"
]
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
}
},
"required": [
"type"
],
"default": {
"type": "email",
"fontSize": 12,
"textAlign": "left",
"overflow": "auto"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"DATE"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
],
"default": "auto"
},
"type": {
"type": "string",
"enum": [
"date"
]
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
}
},
"required": [
"type"
],
"default": {
"type": "date",
"fontSize": 12,
"textAlign": "left",
"overflow": "auto"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"TEXT"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
},
"characterLimit": {
"type": "number",
"minimum": 0
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"lineHeight": {
"type": "number",
"nullable": true,
"minimum": 1,
"maximum": 10
},
"letterSpacing": {
"type": "number",
"nullable": true,
"minimum": 0,
"maximum": 100
},
"verticalAlign": {
"type": "string",
"nullable": true,
"enum": [
"top",
"middle",
"bottom",
null
]
}
},
"required": [
"type"
],
"default": {
"type": "text",
"fontSize": 12,
"textAlign": "left",
"label": "",
"placeholder": "",
"text": "",
"required": false,
"readOnly": false
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"NUMBER"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"number"
]
},
"numberFormat": {
"type": "string",
"nullable": true
},
"value": {
"type": "string"
},
"minValue": {
"type": "number",
"nullable": true
},
"maxValue": {
"type": "number",
"nullable": true
},
"textAlign": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"lineHeight": {
"type": "number",
"nullable": true,
"minimum": 1,
"maximum": 10
},
"letterSpacing": {
"type": "number",
"nullable": true,
"minimum": 0,
"maximum": 100
},
"verticalAlign": {
"type": "string",
"nullable": true,
"enum": [
"top",
"middle",
"bottom",
null
]
}
},
"required": [
"type"
],
"default": {
"type": "number",
"fontSize": 12,
"textAlign": "left",
"label": "",
"placeholder": "",
"required": false,
"readOnly": false
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"RADIO"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"radio"
]
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"checked": {
"type": "boolean"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"checked",
"value"
]
}
},
"direction": {
"type": "string",
"enum": [
"vertical",
"horizontal"
],
"default": "vertical"
}
},
"required": [
"type"
],
"default": {
"type": "radio",
"fontSize": 12,
"values": [
{
"id": 1,
"checked": false,
"value": ""
}
],
"required": false,
"readOnly": false,
"direction": "vertical"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"CHECKBOX"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"checkbox"
]
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"checked": {
"type": "boolean"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"checked",
"value"
]
}
},
"validationRule": {
"type": "string"
},
"validationLength": {
"type": "number"
},
"direction": {
"type": "string",
"enum": [
"vertical",
"horizontal"
],
"default": "vertical"
}
},
"required": [
"type"
],
"default": {
"type": "checkbox",
"fontSize": 12,
"values": [
{
"id": 1,
"checked": false,
"value": ""
}
],
"validationRule": "",
"validationLength": 0,
"required": false,
"readOnly": false,
"direction": "vertical"
}
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"DROPDOWN"
]
},
"fieldMeta": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
},
"readOnly": {
"type": "boolean"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 96,
"default": 12
},
"overflow": {
"type": "string",
"enum": [
"auto",
"horizontal",
"vertical",
"crop"
]
},
"type": {
"type": "string",
"enum": [
"dropdown"
]
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
}
},
"required": [
"value"
]
}
},
"defaultValue": {
"type": "string"
}
},
"required": [
"type"
],
"default": {
"type": "dropdown",
"fontSize": 12,
"values": [
{
"value": "Option 1"
}
],
"defaultValue": "",
"required": false,
"readOnly": false
}
}
},
"required": [
"type"
]
}
]
},
{
"type": "object",
"properties": {
"identifier": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"page": {
"type": "number",
"minimum": 1
},
"positionX": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"positionY": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"page",
"positionX",
"positionY",
"width",
"height"
]
}
]
}
}
},
"required": [
"email",
"name",
"role"
]
}
},
"meta": {
"type": "object",
"properties": {
"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"
]
},
"distributionMethod": {
"type": "string",
"enum": [
"EMAIL",
"NONE"
]
},
"signingOrder": {
"type": "string",
"enum": [
"PARALLEL",
"SEQUENTIAL"
]
},
"allowDictateNextSigner": {
"type": "boolean"
},
"redirectUrl": {
"type": "string"
},
"language": {
"type": "string",
"enum": [
"en",
"es"
]
},
"typedSignatureEnabled": {
"type": "boolean"
},
"uploadSignatureEnabled": {
"type": "boolean"
},
"drawSignatureEnabled": {
"type": "boolean"
},
"emailId": {
"type": "string",
"nullable": true
},
"emailReplyTo": {
"type": "string",
"nullable": true,
"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}])?)*$"
},
"emailSettings": {
"type": "object",
"nullable": true,
"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
}
},
"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"
]
}
]
},
"reminderSettings": {
"type": "object",
"nullable": true,
"properties": {
"sendAfter": {
"anyOf": [
{
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": [
"day",
"week",
"month"
]
},
"amount": {
"type": "integer",
"minimum": 1
}
},
"required": [
"unit",
"amount"
]
},
{
"type": "object",
"properties": {
"disabled": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"disabled"
]
}
]
},
"repeatEvery": {
"anyOf": [
{
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": [
"day",
"week",
"month"
]
},
"amount": {
"type": "integer",
"minimum": 1
}
},
"required": [
"unit",
"amount"
]
},
{
"type": "object",
"properties": {
"disabled": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"disabled"
]
}
]
}
},
"required": [
"sendAfter",
"repeatEvery"
]
}
}
},
"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"
]
}
}
},
"required": [
"title",
"type"
]
},
"files": {
"type": "array",
"items": {}
}
},
"required": [
"payload"
]
}Respuesta de éxito
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"
}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-create.