SDK de Chaindoc

SDK oficiales para una integración perfecta con Chaindoc. Compatibilidad total con TypeScript, cero dependencias y diseño independiente del marco para aplicaciones backend y frontend.

SDK disponibles

SDK del servidor (@chaindoc_io/server-sdk): integración del backend para Node.js 18+.
SDK integrado (@chaindoc_io/embed-sdk): interfaz de firma frontend para aplicaciones web.
SDK de Python: próximamente.
SDK de PHP: próximamente.

SDK del servidor

El SDK del servidor proporciona una interfaz Node.js segura para la API Chaindoc. Úsala para gestionar documentos, crear solicitudes de firma, gestionar cargas de archivos e integrar la verificación de blockchain en tu backend.

Instalación

npm install @chaindoc_io/server-sdk

Requisitos

Node.js 18 o superior (utiliza la API fetch nativa). Clave API secreta (sk_live_* o sk_test_*)

Inicio rápido

server.ts

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

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

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

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

// 4. Create a 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,
});

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

console.log('Session ID:', session.sessionId);

Integración con Express.js

server.ts

import express from 'express';
import { Chaindoc, ChaindocError } from '@chaindoc_io/server-sdk';
import multer from 'multer';

const app = express();
const upload = multer({ storage: multer.memoryStorage() });

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

// Upload and create document
app.post('/api/documents', upload.single('file'), async (req, res) => {
  try {
    const file = new Blob([req.file!.buffer], { type: req.file!.mimetype });
    const { media } = await chaindoc.media.upload([file]);

    const doc = await chaindoc.documents.create({
      name: req.body.name,
      description: req.body.description || '',
      media: media[0],
      status: 'published',
      hashtags: req.body.hashtags || [],
      meta: req.body.meta || [],
    });

    res.json({ documentId: doc.documentId });
  } catch (error) {
    if (error instanceof ChaindocError) {
      res.status(error.statusCode || 500).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

// Create embedded session for signer
app.post('/api/signing/session', async (req, res) => {
  try {
    const { email, documentId, signatureRequestId } = req.body;

    const session = await chaindoc.embedded.createSession({
      email,
      metadata: { documentId, signatureRequestId },
    });

    res.json({ sessionId: session.sessionId });
  } catch (error) {
    if (error instanceof ChaindocError) {
      res.status(error.statusCode || 500).json({ error: error.message });
    }
  }
});

app.listen(3000);

Rutas de la API de Next.js

app/api/signing/create-session/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { Chaindoc, ChaindocError } from '@chaindoc_io/server-sdk';

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

export async function POST(request: NextRequest) {
  try {
    const { email, documentId, signatureRequestId } = await request.json();

    const session = await chaindoc.embedded.createSession({
      email,
      metadata: { documentId, signatureRequestId },
    });

    return NextResponse.json({
      sessionId: session.sessionId,
      expiresAt: session.expiresAt,
    });
  } catch (error) {
    if (error instanceof ChaindocError) {
      return NextResponse.json(
        { error: error.message },
        { status: error.statusCode || 500 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Gestión de errores

Envuelve siempre las llamadas a la API en bloques try-catch y gestiona ChaindocError de forma específica:

terminal

import { ChaindocError } from '@chaindoc_io/server-sdk';

try {
  const doc = await chaindoc.documents.create({ /* ... */ });
} catch (error) {
  if (error instanceof ChaindocError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    
    switch (error.statusCode) {
      case 400:
        // Bad request - check parameters
        break;
      case 401:
        // Unauthorized - check API key
        break;
      case 404:
        // Not found
        break;
      case 429:
        // Rate limited - SDK will auto-retry
        break;
    }
  }
}

Incrustar SDK

El SDK integrado permite una integración perfecta de la funcionalidad de firma de documentos en aplicaciones web. Gestiona un flujo de firma basado en iframe con comunicación segura entre tu aplicación y Chaindoc.

Instalación

npm install @chaindoc_io/embed-sdk

Características principales

Cero dependencias de tiempo de ejecución. Compatibilidad total con TypeScript. Independiente del marco (React, Vue, Angular, Svelte). Ligero: < 10 KB comprimido con gzip. Seguro: validación del origen y sandboxing de iframes.

Uso básico

terminal

import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

// 1. Initialize SDK (once per page)
const chaindoc = new ChaindocEmbed({
  publicKey: 'pk_live_xxxxxxxxxxxxx',
  environment: 'production',
});

// 2. Get session from your backend
const response = await fetch('/api/signing/create-session', {
  method: 'POST',
  body: JSON.stringify({ documentId, signerEmail }),
});
const { sessionId } = await response.json();

// 3. Open signing flow
const instance = chaindoc.openSignatureFlow({
  sessionId,
  
  onReady: () => {
    console.log('Signing interface loaded');
  },
  
  onSuccess: (data) => {
    console.log('Document signed:', data.signatureId);
    instance.close();
  },
  
  onError: (error) => {
    console.error('Signing failed:', error.code, error.message);
  },
  
  onCancel: () => {
    console.log('User cancelled');
    instance.close();
  },
});

Integración con React

components/SignButton.tsx

import { useCallback, useRef, useEffect } from 'react';
import { ChaindocEmbed, EmbedInstance } from '@chaindoc_io/embed-sdk';

function SignButton({ sessionId }: { sessionId: string }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);
  const instanceRef = useRef<EmbedInstance | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  const handleSign = useCallback(() => {
    if (!sdkRef.current) return;

    instanceRef.current = sdkRef.current.openSignatureFlow({
      sessionId,
      onSuccess: (data) => {
        console.log('Signed!', data.signatureId);
        instanceRef.current?.close();
      },
      onCancel: () => {
        instanceRef.current?.close();
      },
    });
  }, [sessionId]);

  return <button onClick={handleSign}>Sign Document</button>;
}

Integración con Vue 3

SignButton.vue

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { ChaindocEmbed, type EmbedInstance } from '@chaindoc_io/embed-sdk';

const props = defineProps<{ sessionId: string }>();

let sdk: ChaindocEmbed | null = null;
let instance: EmbedInstance | null = null;

onMounted(() => {
  sdk = new ChaindocEmbed({
    publicKey: import.meta.env.VITE_CHAINDOC_PUBLIC_KEY,
  });
});

onUnmounted(() => {
  sdk?.destroy();
});

function openSignature() {
  if (!sdk) return;
  
  instance = sdk.openSignatureFlow({
    sessionId: props.sessionId,
    onSuccess: (data) => {
      console.log('Signed!', data.signatureId);
      instance?.close();
    },
    onCancel: () => {
      instance?.close();
    },
  });
}
</script>

<template>
  <button @click="openSignature">Sign Document</button>
</template>

Modo en línea

En lugar de un modal, incrusta la interfaz de firma directamente en tu página:

terminal

const instance = chaindoc.openSignatureFlow({
  sessionId,
  mode: 'inline',
  container: document.getElementById('signature-container'),
  
  onSuccess: (data) => {
    console.log('Signed!');
  },
});

Temas

Personaliza la apariencia con temas claros u oscuros:

terminal

const instance = chaindoc.openSignatureFlow({
  sessionId,
  theme: 'dark',
  // ... other options
});

// Change theme dynamically
instance.changeTheme('light');

Ejemplo de flujo de trabajo completo

A continuación se muestra un ejemplo completo que combina Server SDK y Embed SDK:

1Backend: Subir documentoUtiliza Server SDK para cargar archivos y crear documentos.

2Backend: crear solicitud de firma.Crea una solicitud de firma con el flujo incrustado habilitado.

3Backend: Generar sesiónCrea una sesión incrustada para cada firmante.

4Interfaz: Inicializar el SDK de incrustación.Inicializa el SDK con la clave pública.

5Interfaz: flujo de firma abierto.Abre la interfaz de firma con el ID de sesión.

6Frontend: gestiona el éxito.Procesa el documento firmado y actualiza la interfaz de usuario.

// server.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

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

// Upload & create document
const { media } = await chaindoc.media.upload([pdfFile]);
const doc = await chaindoc.documents.create({
  name: 'Contract',
  description: 'Service agreement',
  media: media[0],
  status: 'published',
  hashtags: ['#contract'],
  meta: [],
});

// 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,
});

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

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

Prácticas recomendadas

Inicializa el SDK una vez por cada ciclo de vida de página/componente.
Destruye siempre la instancia SDK al desmontar el componente.
Gestiona todos los eventos de devolución de llamada (onSuccess, onError, onCancel).
Almacena las claves API en variables de entorno.
Utiliza TypeScript para mejorar la seguridad tipográfica.
Implementa un manejo adecuado de errores con ChaindocError.
Prueba con claves de sandbox antes de la implementación en producción.

Configuración del entorno

// Backend
const chaindoc = new Chaindoc({
  secretKey: 'sk_live_xxxxx',
});

// Frontend
const embed = new ChaindocEmbed({
  publicKey: 'pk_live_xxxxx',
  environment: 'production',
});

Próximos pasos

Consulta la documentación de Webhooks para obtener notificaciones en tiempo real. Lee la referencia de la API REST para obtener la documentación completa de los puntos finales. Explora ejemplos específicos del marco en el repositorio de GitHub.

Documentation

SDK de Chaindoc

SDK disponibles

SDK del servidor

Instalación

Inicio rápido

Integración con Express.js

Rutas de la API de Next.js

Gestión de errores

Incrustar SDK

Instalación

Uso básico

Integración con React

Integración con Vue 3

Modo en línea

Temas

Ejemplo de flujo de trabajo completo

Prácticas recomendadas

Configuración del entorno