Integración de API

Integra Chaindoc en tus aplicaciones con nuestra potente API REST y nuestros SDK. Automatiza los flujos de trabajo de documentos, recopila firmas y sincroniza eventos en tiempo real.

Resumen

Chaindoc proporciona una API REST completa que te permite crear flujos de trabajo personalizados para la firma de documentos, automatizar procesos e integrarlos con tus sistemas existentes. La API está diseñada para desarrolladores con soporte completo para TypeScript y reintentos automáticos.

Introducción

1. Obtén acceso a la API.

2. Elige el método de integración.

Chaindoc ofrece tres enfoques de integración:

• API REST: solicitudes HTTP directas para una flexibilidad máxima.
• SDK del servidor: SDK de Node.js con seguridad de tipos y reintentos automáticos (@chaindoc_io/server-sdk).
• SDK integrado: interfaz de firma frontend para aplicaciones web (@chaindoc_io/embed-sdk).

3. Ejemplo rápido

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": []
  }'

Conceptos básicos de la API

Autenticación

Todas las solicitudes de API requieren autenticación mediante claves API en el encabezado de autorización:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Claves públicas (pk_): acceso de solo lectura para aplicaciones frontend.
• Claves secretas (sk_): acceso completo de lectura/escritura para servidores backend.
• Claves de prueba (pk_test_, sk_test_): para la puesta en escena/desarrollo.
• Claves activas (pk_live_, sk_live_): para producción.

Límites de velocidad

Los puntos finales de la API tienen límites de velocidad para garantizar un uso justo:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

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

Gestión de errores

La API devuelve códigos de estado HTTP estándar con mensajes de error detallados:

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

Patrones de integración comunes

Flujo de carga y firma de documentos

Flujo de trabajo solo en backend

Para los casos en los que los firmantes no utilicen tu interfaz:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Procesamiento masivo de documentos

// Process multiple documents in batch
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' }],
  });
}

Funciones avanzadas

Webhooks

Recibe notificaciones en tiempo real sobre eventos relacionados con los documentos:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Integración KYC

Integra la verificación de identidad para flujos de trabajo de alta seguridad:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Control de acceso

Gestiona los permisos de los documentos con un control de acceso granular:

// Update document access rights
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' }, // Team role
  ],
});

Prácticas recomendadas

• Almacena las claves API en variables de entorno, nunca en código.
• Utiliza claves de prueba para el desarrollo y claves activas para la producción.
• Implementa un retroceso exponencial para el manejo de límites de velocidad.
• Verifica las firmas de los webhooks para evitar ataques de repetición.
• Almacenar en caché las respuestas de la API cuando sea apropiado.
• Sube los archivos antes de crear documentos para obtener un mejor rendimiento.
• Utiliza la paginación para conjuntos de datos grandes.
• Supervisa los encabezados de límite de velocidad y ajusta la frecuencia de las solicitudes.

Ejemplos de integraciones

Plataforma de comercio electrónico

Genera y firma automáticamente contratos de compra para pedidos de alto valor.

Sistema de RR. HH.

Integra con HRIS para la firma automatizada de contratos de trabajo durante la incorporación.

Integración CRM

Crea solicitudes de firma directamente desde los registros de clientes en Salesforce, HubSpot o CRM personalizado.

Sistema de gestión de documentos

Añadid la verificación blockchain al DMS existente para obtener registros de auditoría a prueba de manipulaciones.

Recursos

• Documentación de la API: referencia completa de la API REST con todos los puntos finales.
• SDK: documentación del SDK del servidor y del SDK integrado con ejemplos de marcos.
• Webhooks: guía de configuración de notificaciones de eventos en tiempo real.
• Inicio rápido: pon en marcha tu primera integración en 10 minutos.
• Ejemplos de GitHub: integraciones de muestra y fragmentos de código.