Installation

Intégrez les SDK Chaindoc dans votre projet. Il existe deux packages : le Server SDK pour le backend (documents, signatures, vérification) et l'Embed SDK pour intégrer une interface de signature dans votre frontend.

Avant de commencer

Si vous n'avez pas encore de compte, commencez par le guide de démarrage rapide pour en créer un.

Server SDK

Le Server SDK gère tout le backend : création de documents, envoi de demandes de signature, gestion d'équipes et déclenchement de vérification blockchain. C'est un wrapper léger autour de l'API REST, donc si vous avez lu la documentation de l'API, les noms des méthodes vous seront familiers.

Installer le package

npm install @chaindoc_io/server-sdk

Configurer les variables d'environnement

Créez un fichier `.env` à la racine de votre projet. Vous aurez besoin de votre clé secrète ici.

# 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

Initialiser le SDK

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

La configuration de base suffit pour la plupart des projets. Les paramètres de nouvelle tentative valent la peine d'être ajustés si vous traitez beaucoup de documents en lot, car l'API a des limites de débit.

Vérifier votre connexion

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

Si cela échoue, vérifiez que votre clé secrète commence par `sk_live_` (production) ou `sk_test_` (bac à sable). Le problème le plus courant est d'utiliser accidentellement une clé publique.

Embed SDK

L'Embed SDK vous permet d'afficher l'interface de signature Chaindoc dans votre application web. Vos utilisateurs signent des documents sans quitter votre site. Il fonctionne avec React, Vue, Angular ou JavaScript pur.

Installer le package

npm install @chaindoc_io/embed-sdk

L'option CDN est pratique pour des prototypes rapides ou des sites sans étape de build. Pour la production, utilisez le package npm pour bénéficier du tree-shaking et d'un contrôle de version approprié.

Configurer les variables d'environnement

L'Embed SDK utilise votre clé publique (`pk_`), qui peut être incluse en toute sécurité dans le code côté client.

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

Initialiser dans votre application

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

Configuration spécifique aux frameworks

Ces exemples montrent comment connecter l'Embed SDK en tant que fournisseur ou service dans chaque framework. Si vous utilisez le Server SDK côté backend, vous n'avez pas besoin de fournisseur ; importez-le simplement où vous en avez besoin.

Next.js (App Router)

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

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

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

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

Configuration TypeScript

Les deux SDK sont livrés avec des définitions TypeScript complètes. Vous n'avez pas besoin de packages `@types` supplémentaires.

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

Si vous utilisez une ancienne configuration TypeScript (< 5.0), utilisez `"moduleResolution": "node"` au lieu de `"bundler"`.

Développement vs production

Utilisez des clés de test pendant le développement pour ne pas créer accidentellement de vrais documents ou envoyer des emails de signature à de vrais destinataires.

Configuration de développement

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

Le flag `debug: true` affiche les détails des requêtes/réponses dans la console. C'est verbeux, mais utile pour comprendre pourquoi quelque chose ne fonctionne pas.

Configuration de production

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

Vérifier votre installation

Effectuez ces vérifications pour vous assurer que tout est correctement configuré :

Dépannage

Erreur "Module not found"

Cela signifie généralement que le package ne s'est pas installé correctement ou qu'il y a un conflit de version en cache. Effacez tout et réinstallez :

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

# yarn
rm -rf node_modules yarn.lock
yarn install

Erreurs de type TypeScript

Assurez-vous d'avoir installé les types Node.js et que votre `tsconfig.json` utilise la bonne résolution de module. La plupart des problèmes viennent de paramètres `moduleResolution` incompatibles.

npm install --save-dev @types/node

Erreurs de clé API

Si vous recevez des réponses 401 ou 403, voici ce qu'il faut vérifier :

• 401 Unauthorized signifie que la clé est invalide ou expirée. Régénérez-la dans votre tableau de bord.
• 403 Forbidden signifie que votre plan n'inclut pas l'accès API. Vous avez besoin d'un plan Business.
• Assurez-vous d'utiliser le bon type de clé : les clés `pk_` sont pour l'Embed SDK (frontend), les clés `sk_` sont pour le Server SDK (backend). Les confondre est l'erreur la plus courante.
• Les clés de test (`_test_`) ne fonctionnent que contre le bac à sable. Les clés live (`_live_`) ciblent la production.

Prochaines étapes

Maintenant que les SDK sont installés, choisissez votre prochaine étape :

• Démarrage rapide — envoyez votre première demande de signature en 10 minutes
• Documentation API — référence complète des endpoints avec exemples
• SDKs — fonctionnalités avancées des SDK et guides par framework
• Webhooks — configurez des notifications d'événements en temps réel
• Bonnes pratiques de sécurité — ce qu'il faut configurer avant la mise en production