Chaindoc logoChaindoc

Instalación

Integra los SDKs de Chaindoc en tu proyecto. Hay dos paquetes: el Server SDK para el backend (documentos, firmas, verificación) y el Embed SDK para incorporar una interfaz de firma en tu frontend.

Antes de comenzar

Si aún no tienes una cuenta, comienza con la guía de inicio rápido para configurar una.

Server SDK

El Server SDK gestiona todo en el backend: crear documentos, enviar solicitudes de firma, administrar equipos y activar la verificación blockchain. Es un wrapper ligero alrededor de la REST API, así que si has leído la documentación de la API, los nombres de los métodos te resultarán familiares.

Instalar el paquete

npm install @chaindoc_io/server-sdk

Configurar variables de entorno

Crea un archivo `.env` en la raíz de tu proyecto. Necesitarás tu secret key aquí.

.env
# Production keys
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Staging/Testing keys
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Optional: Custom API endpoint
# CHAINDOC_API_URL=https://api.chaindoc.io

Inicializar el SDK

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

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

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Optional
  timeout: 60000, // 60 seconds
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

La configuración básica es suficiente para la mayoría de los proyectos. Los ajustes de reintentos vale la pena ajustarlos si estás procesando muchos documentos en lotes, ya que la API tiene límites de velocidad.

Verificar tu conexión

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connected to Chaindoc API');
  console.log('User ID:', health.userId);
} else {
  console.error('Connection failed');
}

Si esto falla, verifica que tu secret key comience con `sk_live_` (producción) o `sk_test_` (sandbox). El problema más común es usar accidentalmente una public key.

Embed SDK

El Embed SDK te permite mostrar la interfaz de firma de Chaindoc dentro de tu aplicación web. Tus usuarios firman documentos sin salir de tu sitio. Funciona con React, Vue, Angular o JavaScript puro.

Instalar el paquete

npm install @chaindoc_io/embed-sdk

La opción CDN es útil para prototipos rápidos o sitios sin proceso de build. Para producción, usa el paquete npm para obtener tree-shaking y control de versiones adecuado.

Configurar variables de entorno

El Embed SDK usa tu public key (`pk_`), que es seguro incluir en código del lado del cliente.

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Inicializar en tu aplicación

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return sdkRef.current;
}

Configuración específica por framework

Estos ejemplos muestran cómo conectar el Embed SDK como provider o servicio en cada framework. Si estás usando el Server SDK en el backend, no necesitas un provider; simplemente impórtalo donde lo necesites.

Next.js (App Router)

app/providers.tsx
'use client';

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

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js (Pages Router)

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

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

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

  return <Component {...pageProps} />;
}

Nuxt 3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

Angular

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

Configuración de TypeScript

Ambos SDKs incluyen definiciones completas de TypeScript. No necesitas paquetes `@types` adicionales.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Si estás usando una configuración antigua de TypeScript (< 5.0), usa `"moduleResolution": "node"` en lugar de `"bundler"`.

Desarrollo vs. producción

Usa test keys durante el desarrollo para no crear accidentalmente documentos reales o enviar correos de firma a destinatarios reales.

Configuración de desarrollo

terminal
// Use test keys for development
const chaindoc = new Chaindoc({
  secretKey: 'sk_test_xxxxx',
  baseUrl: 'https://api.chaindoc.io',
});

const embed = new ChaindocEmbed({
  publicKey: 'pk_test_xxxxx',
  environment: 'staging',
  debug: true, // Enable detailed logs
});

La opción `debug: true` imprime detalles de solicitudes/respuestas en la consola. Es verboso, pero útil cuando estás descubriendo por qué algo no funciona.

Configuración de producción

terminal
// Use live keys for production
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!, // sk_live_xxxxx
});

const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!, // pk_live_xxxxx
  environment: 'production',
});

Verificar tu instalación

Revisa estos puntos para asegurarte de que todo esté configurado correctamente:

1Verifica la versión del SDKEjecuta `console.log(ChaindocEmbed.version)` en tu app. Si imprime un número de versión, el paquete se instaló correctamente.

2Prueba la conexión a la APILlama a `chaindoc.healthCheck()` desde tu backend. Una respuesta exitosa significa que tu secret key es válida y la API es accesible.

3Intenta subir un archivoSube un PDF de prueba pequeño usando `chaindoc.media.upload()`. Esto confirma que la autenticación, la red y el manejo de archivos funcionan.

4Abre la interfaz de firmaInicializa el Embed SDK y llama a `openSignatureFlow()` con una sesión de prueba. Si aparece el modal, estás listo.

Solución de problemas

Error "Module not found"

Esto generalmente significa que el paquete no se instaló correctamente o hay un conflicto de versión en caché. Limpia todo y reinstala:

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

Errores de tipos de TypeScript

Asegúrate de tener los tipos de Node.js instalados y que tu `tsconfig.json` use la resolución de módulos correcta. La mayoría de los problemas vienen de ajustes de `moduleResolution` incorrectos.

terminal
npm install --save-dev @types/node

Errores de API key

Si recibes respuestas 401 o 403, aquí está qué revisar:

  • 401 Unauthorized significa que la clave es inválida o expiró. Regenerala en tu panel de control.
  • 403 Forbidden significa que tu plan no incluye acceso a API. Necesitas un plan Business.
  • Asegúrate de usar el tipo de clave correcto: las claves `pk_` son para el Embed SDK (frontend), las claves `sk_` son para el Server SDK (backend). Confundirlas es el error más común.
  • Las test keys (`_test_`) solo funcionan contra el sandbox. Las live keys (`_live_`) apuntan a producción.

Qué hacer a continuación

Ahora que los SDKs están instalados, elige tu siguiente paso: