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 (1, 2, 3… para firma secuencial). |
typeSign | string | — | Rol del firmante ("Firmante" por defecto). |
biometricValid | boolean | — | Validación biométrica avanzada. Add-on de pago. |
basicIdentityValid | boolean | — | Validación de documento contra rostro. Add-on de pago. |
consultRegistry | boolean | — | Consulta en Registraduría. Add-on de pago. |
reqDocument | boolean | — | Exige adjuntar documento de identidad. |
businessName | string | — | Razón social (persona jurídica). |
biometricValid, basicIdentityValid y consultRegistry 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. |
{
"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
}
]
}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/:idBearer/api/documents/add-versions/:idBearerReenviar solicitud de firma
/api/documents/resend-endorsement-documentBearerCuerpo: { "idDocument": "<ObjectId>", "idSigner": "<ObjectId>" }. Reenvía la notificación de firma al firmante indicado.
