Chaindoc logoChaindoc

Instalação

Guia de instalação completo para SDKs Chaindoc. Configure o SDK do servidor para integração backend e o SDK incorporado para interface de assinatura frontend.

Pré-requisitos

Instalação do SDK do servidor

O SDK do servidor é usado para integração de back-end - gestão de documentos, solicitações de assinatura e verificação de blockchain.

Passo 1: Instalar o pacote

npm install @chaindoc_io/server-sdk

Passo 2: Configurar variáveis de ambiente

Crie um ficheiro .env na raiz do seu projeto:

.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

Passo 3: Inicializar o 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',
  },
});

Passo 4: Verificar a ligação

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

Instalando o SDK incorporado

O Embed SDK fornece uma interface de assinatura para aplicações web. Funciona com qualquer estrutura JavaScript.

Passo 1: Instalar o pacote

npm install @chaindoc_io/embed-sdk

Passo 2: Configurar variáveis de ambiente

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

Passo 3: Inicialize na sua aplicação

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

Configuração específica da estrutura

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

serviços/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();
  }
}

Configuração do TypeScript

Ambos os SDKs incluem definições completas do TypeScript. Não são necessários pacotes @types adicionais.

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

Configuração do ambiente

Ambiente de desenvolvimento

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

Ambiente de produção

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

Verificação

Teste a sua instalação com estas etapas de verificação:

1Verifica a versão do SDKconsole.log(ChaindocEmbed.version); // Deve mostrar o número da versão

2Verifica a ligação da APITeste o ponto final de verificação de integridade para confirmar se as chaves API são válidas

3Carregamento do ficheiro de testeCarregue um pequeno ficheiro de teste para verificar se os pontos finais de mídia funcionam

4Inicializar SDK incorporadoInicialize o SDK e verifique se há erros na consola do navegador

Resolução de problemas

Erro de módulo não 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

Erros do TypeScript

Se você vir erros do TypeScript, certifique-se de que o seu tsconfig.json tenha as configurações corretas de resolução de módulos e que os tipos Node.js estejam instalados.

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

Problemas com chaves API

Próximos passos

  • Dá uma olhada no guia de início rápido para a tua primeira integração
  • Verifique a documentação da API para referência de pontos finais
  • Explore a documentação dos SDKs para ver funcionalidades avançadas
  • Configure Webhooks para notificações em tempo real
  • Junte-se à comunidade de programadores no GitHub para obter suporte