Chaindoc logoChaindoc

Instalação

Adicione os SDKs da Chaindoc ao seu projeto. Existem dois pacotes: o Server SDK para trabalho no backend (documentos, assinaturas, verificação) e o Embed SDK para inserir uma interface de assinatura no seu frontend.

Antes de começar

Se você ainda não tem uma conta, comece com o guia de início rápido para configurar uma.

Server SDK

O Server SDK gerencia tudo no backend: criar documentos, enviar solicitações de assinatura, gerenciar equipes e acionar a verificação blockchain. É um wrapper leve em torno da REST API, então se você já leu a documentação da API, os nomes dos métodos parecerão familiares.

Instalar o pacote

npm install @chaindoc_io/server-sdk

Configurar variáveis de ambiente

Crie um arquivo `.env` na raiz do seu projeto. Você precisará da sua chave secreta aqui.

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

A configuração básica é suficiente para a maioria dos projetos. As configurações de retry valem a pena ajustar se você estiver processando muitos documentos em lote, já que a API tem limites de taxa.

Verificar sua conexã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');
}

Se isso falhar, verifique se sua chave secreta começa com `sk_live_` (produção) ou `sk_test_` (sandbox). O problema mais comum é usar acidentalmente uma chave pública.

Embed SDK

O Embed SDK permite que você mostre a interface de assinatura da Chaindoc dentro do seu aplicativo web. Seus usuários assinam documentos sem sair do seu site. Funciona com React, Vue, Angular ou JavaScript puro.

Instalar o pacote

npm install @chaindoc_io/embed-sdk

A opção CDN é útil para protótipos rápidos ou sites sem etapa de build. Para produção, use o pacote npm para obter tree-shaking e controle de versão adequado.

Configurar variáveis de ambiente

O Embed SDK usa sua chave pública (`pk_`), que é segura para incluir no código do lado do cliente.

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

Inicializar no seu app

// 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 por framework

Estes exemplos mostram como conectar o Embed SDK como um provider ou serviço em cada framework. Se você estiver usando o Server SDK no backend, não precisa de um provider; apenas importe-o onde precisar.

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

Configuração do TypeScript

Ambos os SDKs vêm com definições completas de TypeScript. Você não precisa de pacotes `@types` extras.

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

Se você estiver em uma configuração mais antiga do TypeScript (< 5.0), use `"moduleResolution": "node"` em vez de `"bundler"`.

Desenvolvimento vs. produção

Use chaves de teste durante o desenvolvimento para não criar acidentalmente documentos reais ou enviar emails de assinatura para destinatários reais.

Configuração 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
});

A flag `debug: true` imprime detalhes de requisição/resposta no console. É verboso, mas útil quando você está descobrindo por que algo não está funcionando.

Configuração 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',
});

Verificar sua instalação

Execute estas verificações para garantir que tudo esteja conectado corretamente:

1Verificar a versão do SDKExecute `console.log(ChaindocEmbed.version)` no seu app. Se imprimir um número de versão, o pacote foi instalado corretamente.

2Testar a conexão com a APIChame `chaindoc.healthCheck()` do seu backend. Uma resposta bem-sucedida significa que sua chave secreta é válida e a API está acessível.

3Tentar um upload de arquivoFaça upload de um PDF de teste pequeno usando `chaindoc.media.upload()`. Isso confirma que autenticação, rede e manipulação de arquivos funcionam.

4Abrir a UI de assinaturaInicialize o Embed SDK e chame `openSignatureFlow()` com uma sessão de teste. Se o modal aparecer, você está pronto para seguir.

Solução de problemas

Erro "Module not found"

Isso geralmente significa que o pacote não foi instalado corretamente ou há um conflito de versão em cache. Limpe tudo e reinstale:

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

# yarn
rm -rf node_modules yarn.lock
yarn install

Erros de tipo do TypeScript

Certifique-se de ter os tipos do Node.js instalados e seu `tsconfig.json` usa a resolução de módulo correta. A maioria dos problemas vem de configurações `moduleResolution` incompatíveis.

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

Erros de chave de API

Se você estiver recebendo respostas 401 ou 403, aqui está o que verificar:

  • 401 Unauthorized significa que a chave é inválida ou expirou. Regenere-a no seu dashboard.
  • 403 Forbidden significa que seu plano não inclui acesso à API. Você precisa de um plano Business.
  • Certifique-se de usar o tipo de chave correto: chaves `pk_` são para o Embed SDK (frontend), chaves `sk_` são para o Server SDK (backend). Misturá-las é o erro mais comum.
  • Chaves de teste (`_test_`) só funcionam contra o sandbox. Chaves live (`_live_`) acessam a produção.

O que fazer em seguida

Agora que os SDKs estão instalados, escolha seu próximo passo: