Documentos
Crea documentos para firma electrónica, asígnales firmantes y gestiona su ciclo de vida. Base: /api/documents. Todas las rutas requieren Bearer.
El objeto Firmante
Cada documento lleva un arreglo endorsementInput con uno o más firmantes:
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
firstName | string | ✔ | Nombres del firmante. |
lastName | string | ✔ | Apellidos. |
identification | string | ✔ | Número de documento de identidad. |
identificationKind | string | ✔ | Tipo de documento (ej. CC, CE, PAS). |
kindPerson | enum | ✔ | "Persona Natural" o "Persona Juridica". |
email | string | ✔ | Correo del firmante (canal de notificación). |
cellphone | string | ✔ | Celular con indicativo (ej. +57...). |
country | string | ✔ | ObjectId del país (ver Catálogos). |
city | string | — | ObjectId de la ciudad. |
principalSigner | boolean | ✔ | true para el firmante principal. |
iteration | number | ✔ | Orden de firma. Firmantes con el mismo valor firman en paralelo; valores consecutivos (1, 2, 3…) definen firma secuencial. No se permiten saltos. |
typeSign | string | — | Rol del firmante (texto libre). Por defecto "Firmante". Otros ejemplos: "Avalador", "Rep. Legal", "Testigo". |
biometricValid | boolean | — | Validación biométrica avanzada. Add-on de pago. |
basicIdentityValid | boolean | — | Validación de documento contra rostro. Add-on de pago. |
identityValid | boolean | — | Validación de identidad completa (documento + rostro + liveness). Add-on de pago. |
consultRegistry | boolean | — | Consulta en Registraduría. Add-on de pago. |
snapshotCapture | boolean | — | Captura de foto del firmante durante la firma. Add-on de pago. |
biometricSignature | boolean | — | Firma con verificación biométrica facial. Add-on de pago. |
voiceVerification | boolean | — | Verificación de identidad por voz. Add-on de pago. |
antiDeepfake | boolean | — | Detección anti-deepfake en la verificación facial. Add-on de pago. |
reqDocument | boolean | — | Exige adjuntar documento de identidad. |
businessName | string | — | Razón social (persona jurídica). |
identificationRepLegal | string | — | Cédula del representante legal (persona jurídica). |
expeditionDate | string | — | Fecha de expedición del documento de identidad (formato ISO). |
expeditionCity | string | — | Ciudad de expedición del documento de identidad. |
Los firmantes no necesitan estar registrados en Docublock. Reciben la invitación por correo electrónico y firman desde el enlace. El campo typeSign controla el rol visible del firmante en el documento: puedes asignar cualquier texto según tu flujo de negocio.
biometricValid, basicIdentityValid, identityValid, consultRegistry, snapshotCapture, biometricSignature, voiceVerification y antiDeepfake son funcionalidades adicionales que se facturan por separado y deben habilitarse para tu organización. Para activarlas, escríbenos desde app.docublock.co/organizacion o al WhatsApp +57 311 806 8275. Si no están habilitadas, se ignoran.Crear documento desde PDF
/api/documents/create-pdf-base64BearerCampos del cuerpo:
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
name | string | ✔ | Nombre del documento. |
baseFile | string | ✔ | Contenido del PDF en base64. |
filename | string | — | Nombre del archivo (ej. contrato.pdf). |
endorsementInput | Firmante[] | ✔ | Lista de firmantes. |
signatureMode | enum | — | "single" o "independent". |
template | string | — | ObjectId de plantilla asociada. |
directory | string | — | ObjectId del directorio destino. |
relatedInfo | object | — | Metadatos libres para tu integración. |
letterheads | string | — | ObjectId del membrete a aplicar al documento. |
attachments | object[] | — | Archivos PDF anexos que viajan junto al documento principal sin fusionarse en un solo archivo. Cada elemento: { name, file } donde name es el nombre del archivo y file el contenido en base64. |
subsidiary | string | — | ObjectId de la sucursal asociada. |
region | string | — | ObjectId de la región. |
orgArea | string | — | ObjectId del área organizacional. |
subArea | string | — | ObjectId del sub-área. |
{
"name": "Contrato de arrendamiento #1024",
"baseFile": "JVBERi0xLjcKJ...==",
"filename": "contrato-1024.pdf",
"signatureMode": "single",
"endorsementInput": [
{
"firstName": "María",
"lastName": "Ríos",
"identification": "1019234567",
"identificationKind": "CC",
"kindPerson": "Persona Natural",
"email": "maria@ejemplo.com",
"cellphone": "+573001112233",
"country": "661a1fb2a0e9e20423fe6cc8",
"principalSigner": true,
"iteration": 1,
"biometricValid": true
},
{
"firstName": "Carlos",
"lastName": "Gómez",
"identification": "80123456",
"identificationKind": "CC",
"kindPerson": "Persona Natural",
"email": "carlos@ejemplo.com",
"cellphone": "+573009998877",
"country": "661a1fb2a0e9e20423fe6cc8",
"principalSigner": false,
"iteration": 2,
"typeSign": "Avalador"
}
],
"attachments": [
{
"name": "cedula-maria.pdf",
"file": "JVBERi0xLjQK...=="
}
]
}Respuesta 201: el documento creado (con _id, code, path, firmantes y estado inicial). Docublock dispara automáticamente la solicitud de firma a cada firmante.
400 con el mensaje correspondiente.Crear documento desde Word
/api/documents/create-word-base64BearerIgual que el anterior, pero baseFile es un .docx/.doc en base64; Docublock lo convierte a PDF antes de firmar.
Crear un bloque
/api/documents/create-blocks-base64BearerAgrupa varios documentos bajo un mismo flujo de firma. Requiere el arreglo filesBlocks (cada elemento: { name, baseFile, fileType, filename }). Respuesta: { blockId, documents: [{ id, name, code, path }] }.
Creación masiva
/api/documents/create-massive-pdf-base64Bearer/api/documents/create-massive-word-base64Bearer/api/documents/create-massive-blocks-base64BearerCuerpo: { "documents": [ ... ] } (o { "blocks": [ ... ] }). Respuesta: { total, created, failed, results, errors }.
Listar documentos
/api/documents/get-allBearerCuerpo: filtros opcionales + limit, page, order. La organización se aplica automáticamente. Respuesta: { total, totalPages, documents: [...] }.
Obtener un documento
/api/documents/:idBearerDevuelve el documento completo: estado de firma, firmantes, plantilla, versiones, certificado y rastro de auditoría. 404 si no existe.
Actualizar y versionar
/api/documents/:idBearerActualiza los metadatos de un documento existente.
/api/documents/add-versions/:idBearerAgrega una nueva versión del archivo al documento.
Cuando un firmante rechaza, se dispara el evento document.rejected. Configura un webhook para recibir esta y otras notificaciones del ciclo de vida del documento.
Reenviar solicitud de firma
/api/documents/resend-endorsement-documentBearerCuerpo: { "idDocument": "<ObjectId>", "idSigner": "<ObjectId>" }. Reenvía la notificación de firma al firmante indicado.
