Saltar al contenido principal
Documentación técnica
API MVP Base: OpenAPI 0.1.0

API de CILQUM para flujos de firma

Esta documentación resume el contrato técnico actual de CILQUM: autenticación, workspaces, carga de PDF, plantillas, flujos, solicitudes de firma, experiencia pública del firmante, auditoría, certificados y facturación.

Ir a la plataforma Ver confianza
Base URL

Ambiente y versionado

El contrato actual define la API bajo prefijo versionado. En desarrollo local, el servidor documentado expone:

http://localhost:1021/api/v1

En producción, el dominio definitivo debe configurarse por ambiente. Los clientes no deben asumir rutas sin prefijo de versión.

Auth

Autenticación y sesión

La app administrativa envía el access token como Bearer token. El refresh token se maneja como cookie HTTP-only bajo la ruta de autenticación. Ante una respuesta 401, el frontend debe llamar a refresh y reintentar una sola vez.

Authorization: Bearer <access_token>
  • No guardar refresh token en localStorage
  • Reintentar solo una vez después de 401
  • Cerrar sesión si refresh falla
  • No usar rutas privadas sin workspace activo
Multi-tenant

Workspace context

Todas las rutas privadas de negocio están asociadas a un workspace. El backend debe validar membresía activa y rol antes de ejecutar handlers. El frontend nunca debe asumir que un ID global es suficiente sin contexto de workspace.

/workspaces/{workspaceId}/flows
Módulos

Capacidades cubiertas por la API

Auth

Registro, login, refresh, recuperación de contraseña, verificación de email y usuario actual.

Workspaces

Creación y consulta de espacios de trabajo; todas las rutas privadas de negocio dependen del workspace.

Documents

Carga de documentos PDF mediante multipart/form-data y administración de documentos por workspace.

Templates / Acrofill

Plantillas reutilizables, campos de firma, texto, fecha, checkbox, iniciales, DNI, nombre y correo.

Flows

Creación y consulta de flujos configurables asociados a documentos y plantillas.

Signing Requests

Generación de solicitudes de firma y enlaces públicos para firmantes.

Public Signing

Resolución del token público, validación de identidad, captura de firma y descarga final.

Audit / Dashboard

Eventos auditables del workspace y métricas operativas para seguimiento.

Certificates

Perfil de certificado, uso de certificado y registro de éxito o falla en finalización de PDF.

Billing

Créditos, checkout y navegación controlada por proveedor de pago cuando aplique.

Referencia rápida

Endpoints principales

POST /auth/register

Crear usuario inicial.

POST /auth/login

Obtener access token y sesión.

GET /auth/me

Consultar usuario autenticado.

GET / POST /workspaces

Listar o crear workspaces.

POST /workspaces/{workspaceId}/documents/upload

Subir PDF al workspace.

GET / POST /workspaces/{workspaceId}/templates

Listar o crear plantillas.

GET / POST /workspaces/{workspaceId}/flows

Listar o crear flujos.

GET / POST /workspaces/{workspaceId}/signing-requests

Listar o crear solicitudes de firma.

GET /public/sign/{token}

Resolver estado público de firma.

POST /public/sign/{token}/identity

Validar identidad del firmante.

POST /public/sign/{token}/signature

Registrar firma del firmante.

GET /workspaces/{workspaceId}/audit-events

Consultar eventos auditables.

Public signing

Secuencia pública de firma

Las rutas públicas no usan autenticación de usuario. El firmante accede con un token público. El backend almacena solo el hash del token y resuelve el estado permitido para ese flujo.

  1. 1GET /public/sign/{token}
  2. 2POST /public/sign/{token}/identity
  3. 3POST /public/sign/{token}/signature
  4. 4GET /public/sign/{token}/pdf cuando el flujo esté completo
Errores

Formato estándar de error

El frontend debe mostrar mensajes accionables usando el campo message y registrar code/details para diagnóstico técnico.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": {}
  }
}
Acrofill

Campos soportados en plantillas

Cada campo de firma debe incluir signer_role_id para vincular el campo con el rol del firmante dentro del flujo.

signature text date checkbox initials number email dni full_name
Buenas prácticas

Recomendaciones de integración

  • Usar siempre workspaceId en rutas privadas.
  • No exponer tokens públicos en logs del cliente.
  • Validar tamaño y tipo de PDF antes de subir.
  • Manejar 401 con refresh y un solo reintento.
  • Mostrar estados de firma de forma explícita al usuario.
  • Registrar errores técnicos con code y details.
  • No asumir disponibilidad de API enterprise sin plan contratado.
  • Probar flujos públicos en ambiente controlado antes de producción.