Chaindoc logoChaindoc

Installation

Integriere die Chaindoc SDKs in dein Projekt. Es gibt zwei Pakete: Das Server SDK für Backend-Aufgaben (Dokumente, Signaturen, Verifizierung) und das Embed SDK zum Einbetten einer Signing-Oberfläche in dein Frontend.

Bevor du startest

Falls du noch kein Konto hast, starte mit dem Quick-Start-Guide, um eines einzurichten.

Server SDK

Das Server SDK kümmert sich um alles im Backend: Dokumente erstellen, Signaturanfragen senden, Teams verwalten und Blockchain-Verifizierung auslösen. Es ist ein dünner Wrapper um die REST API – wenn du die API-Dokumentation kennst, werden dir die Methodennamen vertraut vorkommen.

Paket installieren

npm install @chaindoc_io/server-sdk

Umgebungsvariablen einrichten

Erstelle eine `.env`-Datei im Projekt-Root. Hier brauchst du deinen Secret Key.

.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

SDK initialisieren

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

Die Basis-Konfiguration reicht für die meisten Projekte aus. Die Retry-Einstellungen lohnen sich, wenn du viele Dokumente im Batch verarbeitest – die API hat schließlich Rate-Limits.

Verbindung überprüfen

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

Falls das fehlschlägt, prüfe nochmal, ob dein Secret Key mit `sk_live_` (Production) oder `sk_test_` (Sandbox) beginnt. Das häufigste Problem: versehentlich einen Public Key verwendet.

Embed SDK

Das Embed SDK zeigt die Chaindoc Signing-Oberfläche direkt in deiner Web-App an. Deine User signieren Dokumente, ohne deine Seite zu verlassen. Es funktioniert mit React, Vue, Angular oder plain JavaScript.

Paket installieren

npm install @chaindoc_io/embed-sdk

Die CDN-Option ist praktisch für schnelle Prototypen oder Seiten ohne Build-Step. Für Production nimm besser das npm-Paket – dann hast du Tree-Shaking und ordentliche Versionskontrolle.

Umgebungsvariablen einrichten

Das Embed SDK verwendet deinen Public Key (`pk_`), der sicher im Client-Code enthalten sein darf.

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

In der App initialisieren

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

Framework-spezifisches Setup

Diese Beispiele zeigen, wie du das Embed SDK als Provider oder Service in jedem Framework einbindest. Falls du das Server SDK im Backend nutzt, brauchst du keinen Provider – importier es einfach dort, wo du es brauchst.

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

TypeScript-Konfiguration

Beide SDKs kommen mit vollständigen TypeScript-Definitionen. Du brauchst keine zusätzlichen `@types`-Pakete.

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

Falls du eine ältere TypeScript-Version (< 5.0) nutzt, verwende stattdessen "moduleResolution": "node".

Entwicklung vs. Production

Nutze Test-Keys während der Entwicklung, damit du nicht versehentlich echte Dokumente erstellst oder Signatur-E-Mails an echte Empfänger schickst.

Entwicklungs-Setup

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

Das Flag `debug: true` schreibt Request-/Response-Details in die Konsole. Es ist ziemlich gesprächig, aber hilfreich, wenn du herausfinden willst, warum etwas nicht funktioniert.

Production-Setup

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

Installation überprüfen

Geh diese Checks durch, um sicherzustellen, dass alles richtig verdrahtet ist:

1SDK-Version prüfenFühre `console.log(ChaindocEmbed.version)` in deiner App aus. Wenn eine Versionsnummer ausgegeben wird, ist das Paket korrekt installiert.

2API-Verbindung testenRufe `chaindoc.healthCheck()` von deinem Backend auf. Eine erfolgreiche Response bedeutet, dass dein Secret Key gültig ist und die API erreichbar.

3Datei-Upload testenLade ein kleines Test-PDF mit `chaindoc.media.upload()` hoch. Das bestätigt, dass Auth, Netzwerk und Dateihandling funktionieren.

4Signing-UI öffnenInitialisiere das Embed SDK und rufe `openSignatureFlow()` mit einer Test-Session auf. Wenn das Modal erscheint, bist du startklar.

Fehlerbehebung

"Module not found"-Fehler

Das bedeutet meist, dass das Paket nicht richtig installiert wurde oder ein Cache-Konflikt vorliegt. Lösche alles und installiere neu:

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

# yarn
rm -rf node_modules yarn.lock
yarn install

TypeScript-Typfehler

Stell sicher, dass du die Node.js-Typen installiert hast und deine `tsconfig.json` die richtige Modulauflösung verwendet. Die meisten Probleme kommen von nicht passenden `moduleResolution`-Einstellungen.

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

API-Key-Fehler

Wenn du 401- oder 403-Fehler bekommst, hier die Checkliste:

  • 401 Unauthorized bedeutet, der Key ist ungültig oder abgelaufen. Generiere ihn neu in deinem Dashboard.
  • 403 Forbidden bedeutet, dein Plan beinhaltet keinen API-Zugriff. Du brauchst einen Business-Plan.
  • Achte auf den richtigen Key-Typ: `pk_`-Keys sind für das Embed SDK (Frontend), `sk_`-Keys für das Server SDK (Backend). Die zu verwechseln ist der häufigste Fehler.
  • Test-Keys (`_test_`) funktionieren nur gegen die Sandbox. Live-Keys (`_live_`) sprechen Production an.

Was als Nächstes?

Jetzt, wo die SDKs installiert sind, wähl deinen nächsten Schritt: