Chaindoc logoChaindoc

Referencia de la API REST de Chaindoc

Referencia completa para integrar la API REST de Chaindoc en tus aplicaciones. Gestiona documentos, firmas, verificación de cadenas de bloques y flujos de trabajo de firma integrados.

Resumen

La API REST de Chaindoc proporciona acceso programático a la gestión de documentos, la verificación de cadenas de bloques y la funcionalidad de firma digital. La API está diseñada para la integración entre servidores y admite claves API públicas y secretas.

Características principales

  • Gestión de documentos: crea, actualiza y gestiona documentos con verificación mediante cadena de bloques.
  • Firmas digitales: solicita y recopila firmas digitales de varias partes.
  • Verificación de cadena de bloques: verifica la autenticidad de los documentos en redes de cadena de bloques.
  • Sesiones incrustadas: crea sesiones seguras para los flujos de trabajo de firma frontend.
  • Carga de archivos multimedia: carga archivos (PDF, imágenes, vídeos) para la creación de documentos.
  • Integración KYC: comparte y verifica datos de identidad con Sumsub.

Autenticación

La API de Chaindoc utiliza claves API para la autenticación. Hay dos tipos de claves con diferentes niveles de acceso.

Tipos de claves API

  • Clave pública (pk_): acceso de solo lectura para aplicaciones frontend y verificación.
  • Clave secreta (sk_): acceso completo de lectura y escritura para servidores backend.

Obtención de claves API

1Suscríbete al plan Business.Solo los usuarios del plan Business pueden crear claves API.

2Navega a Acceso a la API.Ve a Configuración → Acceso a la API en tu panel de control.

3Crear clave APIHaz clic en el botón Crear clave API.

4Almacenar de forma seguraGuarda la clave secreta de forma segura (solo se muestra una vez).

Uso de claves API

Incluye tu clave API en el encabezado de autorización con autenticación Bearer:

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

Limitación de velocidad

Los puntos finales de la API tienen límites de velocidad para evitar abusos. Los límites de velocidad varían según el tipo de punto final.

  • Puntos finales generales: 3 solicitudes cada 10 segundos.
  • Carga de archivos multimedia: 3 solicitudes cada 10 segundos.
  • Verificación OTP: 5 solicitudes cada 60 segundos.
  • Operaciones de lectura: 10 solicitudes por cada 60 segundos.
  • Creación de firmas: 20 solicitudes cada 3 segundos.

Cuando se supere el límite de velocidad, recibirás una respuesta 429 Demasiadas solicitudes. Los encabezados de límite de velocidad se incluyen en las respuestas:

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

Gestión de errores

Códigos de estado HTTP

  • 200 - Éxito
  • 201 - Recurso creado correctamente.
  • 400 - Solicitud incorrecta (error de validación)
  • 401 - No autorizado (clave API no válida o faltante)
  • 403 - Prohibido (permisos insuficientes)
  • 404 - Recurso no encontrado
  • 429 - Demasiadas solicitudes (límite de velocidad 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 sobre la clave API

Obtener información sobre la clave API actual.

GET /me

Authorization: Bearer sk_live_xxxxx

Revisión de salud

Verifica la conectividad de la API y la validez de las claves.

GET /health

Authorization: Bearer sk_live_xxxxx

API de documentos

Crear documento

Crea un nuevo documento con verificación blockchain. Cuando el estado se establece en «publicado», 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 conservan para el registro de auditoría.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Actualiza los derechos de acceso a los documentos.

Actualiza la configuración de control de acceso a los documentos.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Verificar documento

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

POST /documents/verify

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

Obtener estado de verificación

Obtener el estado de verificación de la cadena de bloques para una versión del 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 varios destinatarios. Habilita el flujo integrado para la integración del 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 el estado de la solicitud de firma

Comprueba el estado de una solicitud de firma y ve qué firmantes han completado la firma.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Firmar documento

Firma un documento (si el propietario de la clave API es un signatario).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Obtener firmas de usuarios

Obtener todas las firmas del usuario autenticado.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Obtener solicitudes de firma

Obtén todas las solicitudes de firma para el usuario autenticado con soporte de paginación.

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

Authorization: Bearer sk_live_xxxxx

API de carga de medios

Sube archivos para utilizarlos en la creación de documentos. Admite PDF, imágenes y vídeos. Máximo 10 archivos por solicitud.

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

API KYC

Compartir datos KYC

Comparte los datos KYC (Know Your Customer) con los destinatarios para verificar su identidad.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API de sesiones incrustadas

Crea sesiones incrustadas para la firma de documentos en tu aplicación frontend. Las sesiones tienen una validez de 10 minutos.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json