API de firma electrónica con video probatorio y blockchain
Integra firma legal en tu SaaS, ERP o marketplace en horas. API REST simple, webhooks en tiempo real, video probatorio opcional y registro inmutable en blockchain Avalanche. Cumple Ley 527 (Colombia) y normativa equivalente en Latam.
Endpoints principales
La API expone un set acotado de endpoints REST suficientes para cubrir el ciclo de vida completo del documento. Base URL: https://api.validocus.com — las rutas distinguen mayúsculas y no llevan prefijo de versión.
POST /documents/createContract
Crea un documento firmable. Se manda como multipart/form-data, no como JSON: el PDF va en el campo contract como archivo, más title_doc, desc_doc y signers (un arreglo JSON). Devuelve urls_sign, un enlace de firma por firmante. Manda externalReference para correlacionar el documento con un registro de tu sistema.
GET /documents/signStatus/{soli_id}
Estado del documento: pipeline_status, soli_status, la signedPdfUrl cuando ya está completo, y la transacción de blockchain con su enlace al explorador.
PDF firmado
No hay un endpoint de descarga aparte: signStatus devuelve signedPdfUrl, que apunta al PDF final con todas las firmas embebidas. Solo aparece cuando el documento está completo.
POST /documents/getDocumentBlockchainInfo
Datos probatorios: hash SHA-256 del PDF firmado y la transacción en Avalanche. La evidencia por firmante — video, IP, fecha y hora, user agent — viaja en el anexo de auditoría del propio PDF firmado.
POST /documents/deleteContract
Saca de circulación un documento por su id soli. Es un borrado lógico: el registro y su evidencia se conservan, y los firmantes pendientes ya no pueden firmar.
Webhooks: notificaciones en tiempo real
En vez de hacer polling para saber si un documento ya se firmó, Validocus te notifica con webhooks salientes. Configuras una URL HTTPS en el panel y recibes POSTs con estos eventos: document.completed, form.completed, identity.completed, identity.decided y background.completed.
Cada payload lleva el external_reference que mandaste al crear el documento, así que puedes cruzarlo con tu propio registro sin guardar nuestros ids.
Autenticación y webhooks firmados
Autenticación con Bearer tokens emitidos desde el panel de admin, en el header Authorization: Bearer <token>. Las llaves se pueden revocar en cualquier momento sin downtime. Las requests viajan sobre HTTPS con TLS 1.3 mínimo.
Los webhooks salientes se firman con HMAC-SHA256, igual que lo hace Stripe. Cada entrega lleva X-Validocus-Signature y X-Validocus-Timestamp. La firma es el digest hexadecimal de timestamp + "." + cuerpo crudo con tu secreto de webhook: firma el cuerpo tal como llega, antes de parsear el JSON, e incluye el timestamp o la verificación no va a cuadrar.
Casos de uso
SaaS B2B con onboarding contractual
Tu SaaS necesita que el cliente firme un MSA o términos específicos antes de activar la cuenta. Llamas a /contracts y el cliente recibe el contrato firmable sin salir de tu UX de signup. Webhook activa la cuenta cuando firma.
Sistemas ERP y HRIS
Al crear un nuevo colaborador en el HRIS, tu workflow genera contrato laboral desde plantilla, lo manda a Validocus, recolecta firma y archiva el PDF firmado en el legajo digital del colaborador automáticamente.
Marketplaces y plataformas multi-lado
Marketplace de servicios profesionales, plataforma de freelance, fintech de crédito P2P: cada match entre oferta y demanda genera un contrato que debe firmarse antes de ejecutar el servicio o desembolsar el dinero.
Fintech APIs y servicios financieros
Apertura de cuentas, contratos de crédito, pagarés electrónicos, autorización de débito automático. Cumplimiento SARLAFT con video probatorio del cliente declarando origen de fondos. Auditable y verificable.
¿Cómo funciona?
- 1
Creas una cuenta en Validocus y generas una API key desde el panel de administración con los scopes que necesitas.
- 2
Tu backend hace POST /documents/createContract como multipart/form-data con el PDF y los firmantes — Validocus crea el documento y manda las invitaciones por email.
- 3
Cada firmante abre el link en navegador, firma desde celular o desktop y opcionalmente graba video probatorio.
- 4
Validocus genera hash SHA-256 del PDF final firmado y lo registra en blockchain Avalanche. Manda webhook a tu backend.
- 5
Tu backend recibe el webhook document.completed con la URL del PDF firmado, lo archiva y ejecuta tu lógica de negocio (activar cuenta, desembolsar, generar acceso, etc.).
Preguntas frecuentes
¿Qué hace la API de Validocus?
Permite crear contratos firmables programáticamente desde tu sistema (SaaS, ERP, HRIS, fintech, marketplace). Tu backend hace un POST con el PDF y los firmantes, Validocus manda las invitaciones, recolecta las firmas con video probatorio opcional, registra el hash en blockchain Avalanche y te notifica vía webhook cuando todos firman. Tu código no se preocupa por mostrar el PDF ni capturar la firma — todo eso lo manejan los frontends de Validocus en navegador.
¿Qué tipo de autenticación usa?
Bearer tokens emitidos desde el panel de administración. Las requests se hacen sobre HTTPS con el header Authorization: Bearer <token>, y las llaves se pueden revocar en cualquier momento. Los webhooks salientes se firman con HMAC-SHA256 para que valides que la notificación viene de Validocus y no de un atacante.
¿Cómo recibo notificaciones cuando un documento se firma?
Vía webhooks salientes. Configuras una URL HTTPS en el panel y Validocus hace POST a esa URL en cada evento: document.completed, form.completed, identity.completed, identity.decided y background.completed. El payload incluye el id del documento, su nombre, la fecha de completado, una URL de estado y el external_reference que mandaste al crearlo. Cada entrega lleva X-Validocus-Signature y X-Validocus-Timestamp; la firma es el digest hex HMAC-SHA256 de timestamp + '.' + el cuerpo crudo. Si tu endpoint responde con error o no responde, reintentamos con backoff exponencial.
¿Hay SDKs oficiales?
Tenemos ejemplos de integración listos para Node.js (axios/fetch), Python (requests), PHP (Guzzle/cURL) y Go (net/http). No es un SDK con muchas capas — son recipes y snippets directos sobre la API REST que puedes copiar y adaptar. Para integraciones más complejas (orquestación de bulk imports, retries con dead-letter, idempotencia avanzada) tenemos un equipo de DevRel que apoya gratis al onboarding técnico.
¿Puedo personalizar el flujo de firma?
Sí. La API soporta: orden de firma secuencial o paralela, video probatorio obligatorio u opcional por firmante, redirect URL custom al terminar de firmar (para que el usuario vuelva a tu app), plantillas de email personalizadas, branding en colores y logo. Para contratos de alto volumen también puedes pre-llenar campos del PDF (nombre, cédula, fecha) usando un sistema de placeholders en la generación.
¿Cuánto cuesta la API?
Puedes empezar con 30 días de prueba gratis sin tarjeta de crédito. Después tienes planes según el volumen de contratos por mes. Para integradores con volumen alto o necesidades específicas (SLA dedicado, soporte prioritario, ambiente sandbox separado) tenemos planes Enterprise con condiciones a medida — contáctanos.
Empieza a integrar en minutos
30 días de prueba gratis. Sin tarjeta de crédito.
Obtener API key