Chaindoc logoChaindoc

Integración API

La REST API de Chaindoc te permite automatizar flujos de documentos, recopilar firmas y sincronizar eventos en tiempo real. Aquí está el truco: es la misma API que usamos internamente, así que todo lo que puedes hacer en la app web, lo puedes hacer por código.

Qué puedes hacer con la API

Tienes acceso programático a todo lo que hace Chaindoc: subir documentos, crear solicitudes de firma, gestionar equipos y escuchar eventos mediante webhooks.

Tres formas de integrar

Elige la que mejor se adapte a tu stack. En la práctica, la mayoría de apps en producción usan el Server SDK en el backend y el Embed SDK en el frontend.

  • REST API — peticiones HTTP directas, funciona con cualquier lenguaje. Máxima flexibilidad.
  • Server SDK — wrapper type-safe para Node.js con reintentos automáticos y manejo de errores (`@chaindoc_io/server-sdk`)
  • Embed SDK — incrusta una interfaz de firma en tu app para que los usuarios no salgan de tu sitio (`@chaindoc_io/embed-sdk`)

Si aún no has instalado los SDKs, la guía de instalación cubre la configuración con npm para React, Vue, Angular y Next.js.

Ejemplo rápido

Aquí tienes la misma llamada "crear documento" en tres sabores. La versión con SDK es más concisa, pero la llamada REST cruda muestra exactamente qué pasa por la red.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Autenticación

Cada petición necesita una API key en el header Authorization:

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Hay dos tipos de claves, y mezclarlas es el error de integración más común:

  • Public keys (`pk_`) — solo lectura, seguras para el frontend
  • Secret keys (`sk_`) — lectura/escritura completa, solo backend. Nunca expongas estas en código del cliente.
  • Ambas vienen en variantes test (`_test_`) y live (`_live_`). Las claves de prueba apuntan al sandbox.

Límites de tasa

La API devuelve información de límites en los headers de respuesta. Si alcanzas el límite, recibirás una respuesta 429. Espera y reintenta.

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • Endpoints generales: 3 peticiones cada 10 segundos
  • Subida de archivos: 3 peticiones cada 10 segundos
  • Operaciones de lectura: 10 peticiones cada 60 segundos
  • Creación de firmas: 20 peticiones cada 3 segundos

El Server SDK maneja reintentos automáticamente con backoff exponencial. Si usas HTTP directo, implementa la lógica de reintento tú mismo.

Manejo de errores

Los errores vuelven como JSON con código de estado, mensaje y (para errores de validación) una lista de problemas específicos de campos:

terminal
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Códigos comunes: 400 (petición incorrecta), 401 (clave inválida), 403 (el plan no incluye API), 404 (no encontrado), 429 (límite de tasa), 500 (error del servidor). Para errores 5xx, reintenta con backoff.

Patrones de integración comunes

Flujo completo de firma (embebido)

El patrón más habitual: subes un documento, lo envías para firmar y muestras la interfaz de firma dentro de tu app.

1Subir el archivoPOST /media/upload — envía el PDF, doc de Office o imagen.

2Crear el documentoPOST /documents — establece status='published' para activar la verificación blockchain.

3Crear solicitud de firmaPOST /signatures/requests — añade destinatarios, establece el orden de firma y la fecha límite.

4Crear sesión embebidaPOST /embedded/sessions — esto te da un sessionId para cada firmante.

5Abrir la interfaz de firmaPasa el sessionId al método openSignatureFlow() del Embed SDK.

6Escuchar la finalizaciónConfigura un webhook para el evento signature.request.completed, o consulta GET /signatures/requests/:id/status.

La guía de inicio rápido tiene el código completo para este flujo.

Firma por email (sin embeber)

Si los firmantes no usan tu app, establece `embeddedFlow: false`. Chaindoc les envía un email con un enlace para firmar. Sigues recibiendo notificaciones webhook cuando firman.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Los firmantes reciben enlaces por email
  message: 'Please review and sign this document',
});

Procesamiento masivo de documentos

Para importaciones por lotes, itera sobre tus archivos y sube cada uno. Vigila los límites de tasa. Si procesas cientos de documentos, añade una pequeña pausa entre peticiones o usa la lógica de reintento del SDK.

terminal
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Integración KYC

Para flujos de alta seguridad, exige verificación de identidad antes de firmar. Chaindoc se integra con Sumsub para KYC. Establece `isKycRequired: true` en la solicitud de firma, y los firmantes pasarán por verificación de identidad antes de poder firmar.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Opcional: pre-verificado
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Control de acceso vía API

Puedes establecer permisos de documentos programáticamente. Restringe el acceso a emails específicos o roles de equipo:

terminal
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Buenas prácticas

  • Mantén las API keys en variables de entorno. Nunca las hagas commit al control de versiones.
  • Usa claves de prueba (`sk_test_`) para desarrollo. Las claves live (`sk_live_`) apuntan a producción.
  • Implementa backoff exponencial para respuestas 429. El SDK hace esto automáticamente.
  • Verifica las firmas de webhook con HMAC para prevenir ataques de repetición.
  • Sube archivos antes de crear documentos. La API necesita el ID de media del paso de subida.
  • Usa paginación para endpoints que devuelven listas. No obtengas todo de una vez.
  • Consulta la guía de seguridad antes de salir a producción.

Casos de uso

Algunos patrones del mundo real que los equipos construyen con la API:

  • E-commerce — genera automáticamente acuerdos de compra para pedidos de alto valor y envíalos para firmar al finalizar
  • Onboarding RRHH — crea contratos de empleo desde plantillas y envíalos a nuevos empleados en su primer día
  • Integración CRM — activa solicitudes de firma desde registros de tratos de Salesforce o HubSpot
  • Archivo documental — añade verificación blockchain a documentos en tu sistema de almacenamiento existente

Qué hacer a continuación

  • Documentación API — referencia completa de endpoints con ejemplos de petición/respuesta
  • SDKs — Server SDK y Embed SDK con guías específicas por framework
  • Webhooks — configura notificaciones de eventos en tiempo real
  • Inicio rápido — pon tu primera integración en marcha en 10 minutos
  • Instalación — configuración npm para todos los frameworks soportados