Sobres y documentos
Crea, consulta, configura y distribuye sobres de documentos.
Un sobre reúne uno o varios PDFs y el proceso de sus destinatarios. Usa type: "DOCUMENT" para un documento concreto y type: "TEMPLATE" para una plantilla reutilizable.
Operaciones principales
| Acción | Método y ruta |
|---|---|
| Listar | GET /envelope |
| Obtener uno | GET /envelope/ seguido del envelopeId |
| Obtener varios | POST /envelope/get-many |
| Crear con PDFs | POST /envelope/create |
| Actualizar | POST /envelope/update |
| Duplicar | POST /envelope/duplicate |
| Distribuir | POST /envelope/distribute |
| Redistribuir | POST /envelope/redistribute |
| Cancelar | POST /envelope/cancel |
| Eliminar | POST /envelope/delete |
Crear y usar un sobre requiere multipart/form-data; actualizar y distribuir usa JSON. Deja que tu cliente genere el límite del formulario multipart.
Busca y consulta
curl --fail-with-body --get \
'https://business.digito.do/api/v2/envelope' \
-H "Authorization: $DIGITO_API_TOKEN" \
--data-urlencode 'type=DOCUMENT' \
--data-urlencode 'status=PENDING' \
--data-urlencode 'page=1' \
--data-urlencode 'perPage=20'query permite buscar; folderId, source y templateId permiten acotar resultados. La paginación devuelve currentPage y totalPages junto con data y count.
Configura el borrador
curl --fail-with-body \
'https://business.digito.do/api/v2/envelope/update' \
-H "Authorization: $DIGITO_API_TOKEN" \
-H 'Content-Type: application/json' \
--data '{
"envelopeId": "envelope_ejemplo",
"data": {
"title": "Contrato de servicios",
"externalId": "contrato-001"
},
"meta": {
"language": "es",
"timezone": "America/Santo_Domingo"
}
}'data contiene propiedades del sobre; meta contiene configuración del proceso. Comprueba el estado antes de cambiar destinatarios, archivos o campos. No presupongas que las modificaciones siguen permitidas después de distribuir.
Relaciona los recursos de un sobre
Esta selección del detalle muestra cómo guardar referencias; el objeto completo contiene más propiedades:
{
"id": "envelope_ejemplo",
"type": "DOCUMENT",
"status": "DRAFT",
"teamId": 42,
"externalId": "contrato-001",
"envelopeItems": [
{
"id": "item_ejemplo",
"title": "Contrato",
"order": 1
}
],
"recipients": [
{
"id": 123,
"email": "ana@example.com",
"role": "SIGNER"
}
],
"fields": [
{
"id": 456,
"envelopeItemId": "item_ejemplo",
"recipientId": 123,
"type": "SIGNATURE"
}
]
}El envelopeId identifica el proceso; envelopeItemId identifica un PDF; recipientId y fieldId identifican participantes y campos. Para una plantilla, usa el id del nuevo sobre después de /envelope/use y vuelve a consultar sus relaciones.
Interpreta el estado
status | Uso en tu aplicación |
|---|---|
DRAFT | Preparación y revisión antes de distribuir. |
PENDING | El proceso está pendiente de sus destinatarios. |
COMPLETED | El sobre ha terminado; puedes comprobar las descargas finales. |
REJECTED | Un destinatario rechazó el proceso; revisa el detalle. |
CANCELLED | El sobre se canceló. |
No marques un contrato como firmado únicamente porque una distribución fue correcta. Consulta el estado del sobre y de sus destinatarios. Conserva externalId para enlazarlo con tu sistema; este campo no garantiza deduplicación de solicitudes.
El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. Una sesión abierta en Business, una clave de API, un token de destinatario o un token de integración no sustituye esta autenticación.
Prepara un documento paso a paso o consulta la referencia de sobres.