Chaindoc logoChaindoc

Instalación

Guía de instalación completa para los SDK de Chaindoc. Configura el SDK del servidor para la integración del backend y el SDK de incrustación para la interfaz de firma del frontend.

Requisitos previos

Instalación del SDK del servidor

El SDK del servidor se utiliza para la integración del backend: gestión de documentos, solicitudes de firma y verificación de blockchain.

Paso 1: Instalar el paquete

npm install @chaindoc_io/server-sdk

Paso 2: Configura las variables de entorno.

Crea un archivo .env en la raíz de tu proyecto:

.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

Paso 3: 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',
  },
});

Paso 4: Verificar la 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');
}

Instalación del SDK integrado

El SDK integrado proporciona una interfaz de firma para aplicaciones web. Funciona con cualquier marco de JavaScript.

Paso 1: Instalar el paquete

npm install @chaindoc_io/embed-sdk

Paso 2: Configura las variables de entorno.

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

Paso 3: Inicializa 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 del marco

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 (enrutador de páginas)

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 SDK incluyen definiciones completas de TypeScript. No se necesitan 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
  }
}

Configuración del entorno

Entorno 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
});

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

Verificación

Prueba tu instalación con estos pasos de verificación:

1Comprueba la versión del SDK.console.log(ChaindocEmbed.version); // Debe mostrar el número de versión.

2Verifica la conexión API.Prueba el punto final de verificación del estado para confirmar que las claves API son válidas.

3Prueba de carga de archivosSube un pequeño archivo de prueba para verificar que los puntos finales multimedia funcionan.

4Inicializar SDK integradoInicializa el SDK y comprueba si hay errores en la consola del navegador.

Solución de problemas

Error de módulo no encontrado

terminal
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# For yarn
rm -rf node_modules yarn.lock
yarn install

Errores de TypeScript

Si ves errores de TypeScript, asegúrate de que tu tsconfig.json tiene la configuración correcta de resolución de módulos y que los tipos de Node.js están instalados.

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

Problemas con las claves API

Próximos pasos

  • Consulta la guía de inicio rápido para tu primera integración.
  • Consulta la documentación de la API para obtener referencias sobre los puntos finales.
  • Explora la documentación de los SDK para conocer las funciones avanzadas.
  • Configura Webhooks para recibir notificaciones en tiempo real.
  • Únete a la comunidad de desarrolladores en GitHub para obtener ayuda.