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 contrato. Base URL: https://api.validocus.com/v1
POST /v1/contracts
Crea un contrato firmable. Recibe el PDF (URL o base64), la lista de firmantes con orden, opciones de video probatorio y URL de callback. Devuelve el contract_id.
GET /v1/contracts/{id}
Estado del contrato: lista de firmantes, quién ya firmó, timestamps, hash actual, blockchain tx hash una vez completo.
GET /v1/contracts/{id}/document
Descarga el PDF firmado final (binario application/pdf) con todas las firmas embebidas. Solo disponible cuando el contrato está en estado completed.
GET /v1/contracts/{id}/evidence
Certificado de evidencia probatoria: hash SHA-256, blockchain tx, video URLs por firmante, IPs, timestamps, user agents. Para archivo legal o auditoría.
POST /v1/contracts/{id}/cancel
Cancela un contrato en curso. Los firmantes pendientes ya no pueden firmar. Útil para cuando el deal se cae o se renegocia.
Webhooks: notificaciones en tiempo real
En vez de hacer polling para saber si un contrato ya se firmó, Validocus te notifica con webhooks salientes. Configuras una URL HTTPS en el panel y recibes POSTs con eventos: contract.created, signer.viewed, signer.signed, contract.completed, contract.rejected.
Autenticación y webhooks firmados
Autenticación con Bearer tokens emitidos desde el panel de admin. Cada API key tiene scopes configurables (read-only, contracts.write, webhooks.manage) y puede revocarse en cualquier momento sin downtime. Las requests viajan sobre HTTPS con TLS 1.3 mínimo.
Los webhooks salientes se firman con HMAC-SHA256. El header X-Validocus-Signature contiene el digest hexadecimal que tu endpoint debe verificar contra un secret compartido para descartar requests falsificadas.
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 /v1/contracts con el PDF y los firmantes — Validocus crea el contrato 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 contract.completed, hace GET /v1/contracts/{id}/document, archiva el PDF firmado 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. Cada cuenta puede generar múltiples API keys con scopes diferentes (read-only, contracts.write, webhooks.manage). Las requests se hacen sobre HTTPS con el header Authorization: Bearer <token>. 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 contrato se firma?
Vía webhooks salientes. Configuras una URL HTTPS en el panel y Validocus hace POST a esa URL en cada evento del ciclo de vida: contract.created, signer.viewed, signer.signed, contract.completed, contract.rejected, contract.expired. El payload incluye el ID del contrato, el ID del firmante, timestamp y hash del documento actual. Si tu endpoint responde con error o no responde, reintentamos con backoff exponencial hasta 24 horas.
¿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