Chaindoc logoChaindoc

Referencia del API REST de Chaindoc

Guía completa de endpoints para el API REST de Chaindoc. Cubre autenticación, documentos, firmas, subida de archivos, sesiones embebidas y verificación blockchain.

Descripción general

El API te da acceso programático a todo lo que hay en Chaindoc: documentos, firmas, verificación blockchain y gestión de equipos. Está diseñado para uso servidor-a-servidor y soporta tanto API keys públicas como secretas.

  • Documentos — crea, actualiza y verifica documentos en blockchain
  • Firmas — envía solicitudes de firma y rastrea su finalización
  • Media — sube PDFs, imágenes y videos (máximo 10 por petición)
  • Sesiones embebidas — crea sesiones de firma para tu frontend (usa el Embed SDK)
  • KYC — comparte y verifica datos de identidad mediante integración con Sumsub

Autenticación

Cada petición necesita una API key en el header Authorization. Existen dos tipos:

Tipos de keys

  • Public key (`pk_`) — solo lectura, segura para código frontend
  • Secret key (`sk_`) — lectura/escritura completa, solo backend. Nunca la expongas en código del lado del cliente.

Obtener tus keys

1Suscríbete al plan BusinessSolo los usuarios del plan Business pueden crear API keys

2Navega a Acceso al APIVe a Configuración → Acceso al API en tu dashboard

3Crea la API keyHaz clic en el botón Crear API Key

4Almacena de forma seguraGuarda la secret key de forma segura (se muestra solo una vez)

Usar las API keys

Incluye tu API key en el header Authorization con autenticación Bearer:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate limiting

Los endpoints del API tienen límites de peticiones para prevenir abusos. Los límites varían según el tipo de endpoint.

  • Endpoints generales: 3 peticiones cada 10 segundos
  • Subida de archivos: 3 peticiones cada 10 segundos
  • Verificación OTP: 5 peticiones cada 60 segundos
  • Operaciones de lectura: 10 peticiones cada 60 segundos
  • Creación de firmas: 20 peticiones cada 3 segundos

Cuando se excede el límite, recibirás una respuesta 429 Too Many Requests. Los headers de rate limit se incluyen en las respuestas:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Manejo de errores

Códigos de estado HTTP

  • 200 - Éxito
  • 201 - Recurso creado correctamente
  • 400 - Petición incorrecta (error de validación)
  • 401 - No autorizado (API key inválida o faltante)
  • 403 - Prohibido (permisos insuficientes)
  • 404 - Recurso no encontrado
  • 429 - Demasiadas peticiones (límite excedido)
  • 500 - Error interno del servidor

Formato de respuesta de error

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

API General

Obtener información de la API key

Obtiene información sobre la API key actual.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

Verifica la conectividad con el API y la validez de la key.

GET /health

Authorization: Bearer sk_live_xxxxx

API de Documentos

Crear documento

Crea un documento nuevo con verificación blockchain. Cuando el estado se establece como 'published', el documento se verifica automáticamente en blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Actualizar documento

Actualiza un documento creando una nueva versión. Las versiones anteriores se preservan para el historial de auditoría.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Actualizar permisos del documento

Actualiza la configuración de control de acceso del documento.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Verificar documento

Verifica la autenticidad del documento usando blockchain. Devuelve el estado de verificación con el hash de transacción y el ID de cadena.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Obtener estado de verificación

Obtiene el estado de verificación blockchain para una versión de documento.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API de Firmas

Crear solicitud de firma

Crea una solicitud de firma para uno o más destinatarios. Activa el flujo embebido para integración con el frontend.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Obtener estado de la solicitud de firma

Verifica el estado de una solicitud de firma y consulta qué firmantes han completado el proceso.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Firmar documento

Firma un documento (si el dueño de la API key es firmante).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Obtener firmas del usuario

Obtiene todas las firmas del usuario autenticado.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Obtener solicitudes de firma

Obtiene todas las solicitudes de firma del usuario autenticado con soporte para paginación.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API de Subida de Archivos

Sube archivos para usar en la creación de documentos. Soporta PDF, imágenes y videos. Máximo 10 archivos por petición.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

API de KYC

Compartir datos KYC

Comparte datos KYC (Know Your Customer) con destinatarios para verificación de identidad.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API de Sesiones Embebidas

Crea sesiones embebidas para la firma de documentos en tu aplicación frontend. Las sesiones son válidas por 10 minutos.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Próximos pasos

  • Integración del API — patrones comunes, mejores prácticas y ejemplos completos de flujos de trabajo
  • SDKs — Server SDK y Embed SDK con guías específicas para frameworks
  • Webhooks — configura notificaciones de eventos en tiempo real
  • Instalación — configuración de npm para todos los frameworks soportados
  • Seguridad — gestión de API keys y cumplimiento