Guía de inicio rápido

Ponte en marcha con Chaindoc en menos de 10 minutos. Esta guía te lleva tanto por la interfaz web como por la API, para que puedas elegir el camino que mejor se adapte a ti.

Firmar a través de la interfaz web

No necesitas ningún código para enviar tu primera solicitud de firma. La aplicación web lo maneja todo: subida, destinatarios, flujo de firma y verificación blockchain.

Paso a paso: tu primera firma

¿Quieres entender los diferentes tipos de firma (simple, avanzada, cualificada)? Eso importa para el cumplimiento. La mayoría de los contratos comerciales funcionan bien con firmas electrónicas simples, pero las industrias reguladas a menudo necesitan firmas avanzadas o cualificadas.

Integración mediante la API

Si estás integrando la firma en tu propia aplicación, usarás la API REST y los SDK de TypeScript. El flujo es el mismo que la interfaz web, solo que automatizado.

1. Obtén tus API keys

El acceso a la API requiere un plan Business. Ve a Configuración > Acceso API en tu panel y crea dos claves:

• Public key (`pk_`) para uso frontend con el Embed SDK
• Secret key (`sk_`) para uso backend con el Server SDK. Mantén esta fuera del código del lado del cliente.

2. Instala el SDK

Elige el SDK que coincida con tu caso de uso. La mayoría de las aplicaciones necesitan ambos: el Server SDK para crear documentos y el Embed SDK para la interfaz de firma.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Para la configuración detallada del framework (React, Vue, Angular, Next.js), consulta la guía de instalación.

3. Sube y crea un documento

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

Establecer `status: 'published'` activa la verificación blockchain automáticamente. Si quieres posponerlo, usa `'draft'` y publica más tarde.

4. Crea una solicitud de firma

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Establece `embeddedFlow: true` si vas a mostrar la interfaz de firma dentro de tu aplicación. Sin eso, los firmantes reciben un enlace a la página de firma alojada de Chaindoc.

5. Muestra la interfaz de firma (frontend)

Esto es opcional. Si estableciste `embeddedFlow: true`, puedes abrir la interfaz de firma directamente dentro de tu aplicación. Primero, crea una sesión en el backend, luego pasa el ID de sesión al frontend.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Verifica el estado y escucha eventos

Puedes consultar el estado, pero los webhooks son una mejor opción para producción. Notificarán a tu servidor en el momento en que ocurra algo.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Configura webhooks (recomendado)

Los webhooks envían eventos a tu servidor en tiempo real, así que no tienes que estar verificando constantemente. Aquí hay un manejador básico de Express:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

En producción, deberías verificar las firmas de los webhooks con HMAC para asegurarte de que el payload realmente vino de Chaindoc. La guía de webhooks cubre eso en detalle.

Ejemplo de flujo de trabajo completo

Esto lo une todo: subir, crear, firmar, verificar. Cópialo, cambia tus API keys, y tendrás un prototipo funcional.

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

A dónde ir a continuación

Ahora que tienes lo básico, aquí hay qué profundizar dependiendo de lo que estés construyendo:

• Instalación — configuración específica del framework para React, Vue, Angular y Next.js
• Documentación de la API — referencia completa de endpoints con ejemplos de solicitud/respuesta
• SDKs — Server SDK y Embed SDK, con guías de integración por framework
• Webhooks — notificaciones de eventos en tiempo real para aplicaciones en producción
• Mejores prácticas de seguridad — qué asegurar antes de salir a producción

Preguntas frecuentes

¿Cuánto tiempo toma la verificación blockchain?

Generalmente de 1 a 5 minutos, dependiendo de la red. Tu documento está disponible de inmediato. La verificación se ejecuta en segundo plano y recibirás un evento webhook cuando termine.

¿Puedo probar la API sin pagar?

El plan gratuito te da acceso a la interfaz web. El acceso a la API necesita un plan Business, pero el entorno sandbox te permite probar todo sin afectar datos reales o usar cuota.

¿Estas firmas son legalmente vinculantes?

Sí. Las firmas de Chaindoc cumplen con eIDAS en Europa, la ESIGN Act y UETA en EE.UU., y regulaciones equivalentes en la mayoría de otras jurisdicciones. La verificación blockchain añade una capa extra de evidencia además de eso, lo cual puede importar en disputas. Consulta la documentación de firmas para detalles sobre qué tipo de firma se adapta a tus necesidades de cumplimiento.

¿Qué formatos de archivo puedo subir?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV y WMV. El tamaño máximo de archivo es de 50MB.