Chaindoc logoChaindoc

Instalacja

Dodaj SDK Chaindoc do swojego projektu. Są dwa pakiety: Server SDK do pracy na backendzie (dokumenty, podpisy, weryfikacja) oraz Embed SDK do osadzania interfejsu podpisywania we frontendzie.

Zanim zaczniesz

Jeśli jeszcze nie masz konta, zacznij od przewodnika szybkiego startu, aby je utworzyć.

Server SDK

Server SDK obsługuje wszystko na backendzie: tworzenie dokumentów, wysyłanie zapytań o podpis, zarządzanie zespołami oraz wyzwalanie weryfikacji blockchain. To cienka warstwa wokół REST API, więc jeśli znasz dokumentację API, nazwy metod będą znajome.

Zainstaluj pakiet

npm install @chaindoc_io/server-sdk

Skonfiguruj zmienne środowiskowe

Utwórz plik `.env` w głównym katalogu projektu. Będziesz potrzebować tutaj swojego klucza sekretnego.

.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

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

Podstawowa konfiguracja wystarczy dla większości projektów. Ustawienia ponawiania warto dostosować, jeśli przetwarzasz dużo dokumentów wsadowo, ponieważ API ma limity rate.

Zweryfikuj połączenie

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

Jeśli to się nie powiedzie, sprawdź czy twój klucz sekretny zaczyna się od `sk_live_` (produkcja) lub `sk_test_` (sandbox). Najczęstszym problemem jest przypadkowe użycie klucza publicznego.

Embed SDK

Embed SDK pozwala wyświetlić interfejs podpisywania Chaindoc wewnątrz twojej aplikacji webowej. Użytkownicy podpisują dokumenty bez opuszczania twojej strony. Działa z React, Vue, Angular lub czystym JavaScript.

Zainstaluj pakiet

npm install @chaindoc_io/embed-sdk

Opcja CDN jest przydatna do szybkich prototypów lub stron bez procesu build. Dla produkcji użyj pakietu npm, aby uzyskać tree-shaking i właściwą kontrolę wersji.

Skonfiguruj zmienne środowiskowe

Embed SDK używa twojego klucza publicznego (`pk_`), który jest bezpieczny do umieszczenia w kodzie po stronie klienta.

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

Zainicjalizuj w aplikacji

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

Konfiguracja specyficzna dla frameworka

Te przykłady pokazują jak podłączyć Embed SDK jako provider lub serwis w każdym frameworku. Jeśli używasz Server SDK na backendzie, nie potrzebujesz providera; po prostu zaimportuj go tam, gdzie jest potrzebny.

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

Konfiguracja TypeScript

Oba SDK zawierają pełne definicje TypeScript. Nie potrzebujesz żadnych dodatkowych pakietów `@types`.

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

Jeśli używasz starszej wersji TypeScript (< 5.0), użyj zamiast tego "moduleResolution": "node" zamiast "bundler".

Dewelopment vs produkcja

Używaj kluczy testowych podczas developmentu, aby przypadkiem nie tworzyć prawdziwych dokumentów ani nie wysyłać maili z prośbą o podpis do faktycznych odbiorców.

Konfiguracja developmentu

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

Flaga `debug: true` wypisuje szczegóły request/response do konsoli. Jest to hałaśliwe, ale przydatne gdy próbujesz dowiedzieć się dlaczego coś nie działa.

Konfiguracja produkcji

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

Zweryfikuj instalację

Przejdź przez te sprawdzenia, aby upewnić się, że wszystko jest poprawnie podłączone:

1Sprawdź wersję SDKUruchom `console.log(ChaindocEmbed.version)` w swojej aplikacji. Jeśli wyświetli numer wersji, pakiet zainstalował się poprawnie.

2Przetestuj połączenie z APIWywołaj `chaindoc.healthCheck()` ze swojego backendu. Pomyślna odpowiedź oznacza, że twój klucz sekretny jest ważny i API jest dostępne.

3Spróbuj wysłać plikWyślij mały testowy PDF używając `chaindoc.media.upload()`. To potwierdzi, że autoryzacja, sieć i obsługa plików działają.

4Otwórz interfejs podpisywaniaZainicjalizuj Embed SDK i wywołaj `openSignatureFlow()` z sesją testową. Jeśli modal się pojawi, wszystko działa.

Rozwiązywanie problemów

Błąd "Module not found"

To zazwyczaj oznacza, że pakiet nie zainstalował się poprawnie lub jest konflikt z wersją w cache. Wyczyść wszystko i przeinstaluj:

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

# yarn
rm -rf node_modules yarn.lock
yarn install

Błędy typów TypeScript

Upewnij się, że masz zainstalowane typy Node.js i twój `tsconfig.json` używa właściwego module resolution. Większość problemów wynika z niedopasowanych ustawień `moduleResolution`.

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

Błędy klucza API

Jeśli dostajesz odpowiedzi 401 lub 403, oto co sprawdzić:

  • 401 Unauthorized oznacza, że klucz jest nieważny lub wygasł. Wygeneruj go ponownie w panelu.
  • 403 Forbidden oznacza, że twój plan nie obejmuje dostępu do API. Potrzebujesz planu Business.
  • Upewnij się, że używasz właściwego typu klucza: klucze `pk_` są dla Embed SDK (frontend), klucze `sk_` są dla Server SDK (backend). Pomyłka jest najczęstszym błędem.
  • Klucze testowe (`_test_`) działają tylko przeciwko sandbox. Klucze live (`_live_`) trafiają do produkcji.

Co zrobić dalej

Teraz, gdy SDK są zainstalowane, wybierz następny krok: