Documentos
Crie documentos para assinatura eletrônica, atribua signatários a eles e gerencie seu ciclo de vida. Base: /api/documents. Todas as rotas exigem Bearer.
O objeto Firmante
Cada documento leva um array endorsementInput com um ou mais signatários:
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
firstName | string | ✔ | Nomes do signatário. |
lastName | string | ✔ | Sobrenomes. |
identification | string | ✔ | Número do documento de identidade. |
identificationKind | string | ✔ | Tipo de documento (ex. CC, CE, PAS). |
kindPerson | enum | ✔ | "Persona Natural" ou "Persona Juridica". |
email | string | ✔ | E-mail do signatário (canal de notificação). |
cellphone | string | ✔ | Celular com código de país (ex. +57...). |
country | string | ✔ | ObjectId do país (ver Catálogos). |
city | string | — | ObjectId da cidade. |
principalSigner | boolean | ✔ | true para o signatário principal. |
iteration | number | ✔ | Ordem de assinatura. Signatários com o mesmo valor assinam em paralelo; valores consecutivos (1, 2, 3…) definem assinatura sequencial. Não são permitidos saltos. |
typeSign | string | — | Papel do signatário (texto livre). Por padrão "Firmante". Outros exemplos: "Avalador", "Rep. Legal", "Testigo". |
biometricValid | boolean | — | Validação biométrica avançada. Add-on pago. |
basicIdentityValid | boolean | — | Validação de documento contra o rosto. Add-on pago. |
identityValid | boolean | — | Validação de identidade completa (documento + rosto + liveness). Add-on pago. |
consultRegistry | boolean | — | Consulta na Registraduría. Add-on pago. |
snapshotCapture | boolean | — | Captura de foto do signatário durante a assinatura. Add-on pago. |
biometricSignature | boolean | — | Assinatura com verificação biométrica facial. Add-on pago. |
voiceVerification | boolean | — | Verificação de identidade por voz. Add-on pago. |
antiDeepfake | boolean | — | Detecção anti-deepfake na verificação facial. Add-on pago. |
reqDocument | boolean | — | Exige anexar documento de identidade. |
businessName | string | — | Razão social (pessoa jurídica). |
identificationRepLegal | string | — | CPF/CNPJ do representante legal (pessoa jurídica). |
expeditionDate | string | — | Data de expedição do documento de identidade (formato ISO). |
expeditionCity | string | — | Cidade de expedição do documento de identidade. |
Os signatários não precisam estar cadastrados na Docublock. Recebem o convite por e-mail e assinam diretamente pelo link. O campo typeSign controla o papel visível do signatário no documento: você pode atribuir qualquer texto conforme o seu fluxo de negócio.
biometricValid, basicIdentityValid, identityValid, consultRegistry, snapshotCapture, biometricSignature, voiceVerification e antiDeepfake são funcionalidades adicionais que são cobradas separadamente e devem ser habilitadas para a sua organização. Para ativá-las, escreva para nós em app.docublock.co/organizacion ou no WhatsApp +57 311 806 8275. Se não estiverem habilitadas, são ignoradas.Criar documento a partir de PDF
/api/documents/create-pdf-base64BearerCampos do corpo:
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
name | string | ✔ | Nome do documento. |
baseFile | string | ✔ | Conteúdo do PDF em base64. |
filename | string | — | Nome do arquivo (ex. contrato.pdf). |
endorsementInput | Firmante[] | ✔ | Lista de signatários. |
signatureMode | enum | — | "single" ou "independent". |
template | string | — | ObjectId do modelo associado. |
directory | string | — | ObjectId do diretório de destino. |
relatedInfo | object | — | Metadados livres para a sua integração. |
letterheads | string | — | ObjectId do cabeçalho a aplicar ao documento. |
attachments | object[] | — | Arquivos PDF anexos que viajam junto ao documento principal sem se fundir em um único arquivo. Cada elemento: { name, file } onde name é o nome do arquivo e file o conteúdo em base64. |
subsidiary | string | — | ObjectId da filial associada. |
region | string | — | ObjectId da região. |
orgArea | string | — | ObjectId da área organizacional. |
subArea | string | — | ObjectId da 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...=="
}
]
}Resposta 201: o documento criado (com _id, code, path, signatários e estado inicial). A Docublock dispara automaticamente a solicitação de assinatura para cada signatário.
400 com a mensagem correspondente.Criar documento a partir de Word
/api/documents/create-word-base64BearerIgual ao anterior, mas baseFile é um .docx/.doc em base64; a Docublock o converte em PDF antes de assinar.
Criar um bloco
/api/documents/create-blocks-base64BearerAgrupa vários documentos sob um mesmo fluxo de assinatura. Requer o array filesBlocks (cada elemento: { name, baseFile, fileType, filename }). Resposta: { blockId, documents: [{ id, name, code, path }] }.
Criação em massa
/api/documents/create-massive-pdf-base64Bearer/api/documents/create-massive-word-base64Bearer/api/documents/create-massive-blocks-base64BearerCorpo: { "documents": [ ... ] } (ou { "blocks": [ ... ] }). Resposta: { total, created, failed, results, errors }.
Listar documentos
/api/documents/get-allBearerCorpo: filtros opcionais + limit, page, order. A organização é aplicada automaticamente. Resposta: { total, totalPages, documents: [...] }.
Obter um documento
/api/documents/:idBearerRetorna o documento completo: estado de assinatura, signatários, modelo, versões, certificado e trilha de auditoria. 404 se não existir.
Atualizar e versionar
/api/documents/:idBearerAtualiza os metadados de um documento existente.
/api/documents/add-versions/:idBearerAdiciona uma nova versão do arquivo ao documento.
Quando um signatário recusa, o evento document.rejected é disparado. Configure um webhook para receber esta e outras notificações do ciclo de vida do documento.
Reenviar solicitação de assinatura
/api/documents/resend-endorsement-documentBearerCorpo: { "idDocument": "<ObjectId>", "idSigner": "<ObjectId>" }. Reenvia a notificação de assinatura ao signatário indicado.
