Installazione

Aggiungi gli SDK di Chaindoc al tuo progetto. Ci sono due pacchetti: il Server SDK per il lavoro backend (documenti, firme, verifica) e l'Embed SDK per integrare un'interfaccia di firma nel tuo frontend.

Prima di iniziare

Se non hai ancora un account, inizia con la guida di avvio rapido per configurarne uno.

Server SDK

Il Server SDK gestisce tutto sul backend: creazione di documenti, invio di richieste di firma, gestione dei team e attivazione della verifica blockchain. È un wrapper sottile attorno alla REST API, quindi se hai letto la documentazione API, i nomi dei metodi ti sembreranno familiari.

Installa il pacchetto

npm install @chaindoc_io/server-sdk

Configura le variabili d'ambiente

Crea un file `.env` nella root del tuo progetto. Avrai bisogno della tua chiave segreta qui.

# Chiavi di produzione
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Chiavi di staging/test
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Opzionale: Endpoint API personalizzato
# CHAINDOC_API_URL=https://api.chaindoc.io

Inizializza l'SDK

import { Chaindoc } from '@chaindoc_io/server-sdk';

// Inizializzazione di base
export const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Configurazione avanzata
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Opzionale
  timeout: 60000, // 60 secondi
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

La configurazione di base è sufficiente per la maggior parte dei progetti. Le impostazioni di retry meritano di essere ottimizzate se stai elaborando molti documenti in batch, poiché l'API ha limiti di rate.

Verifica la tua connessione

// Test della connessione API
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connesso all'API Chaindoc');
  console.log('User ID:', health.userId);
} else {
  console.error('Connessione fallita');
}

Se fallisce, controlla che la tua chiave segreta inizi con `sk_live_` (produzione) o `sk_test_` (sandbox). Il problema più comune è usare accidentalmente una chiave pubblica.

Embed SDK

L'Embed SDK ti permette di mostrare l'interfaccia di firma Chaindoc all'interno della tua web app. I tuoi utenti firmano documenti senza uscire dal tuo sito. Funziona con React, Vue, Angular o JavaScript vanilla.

Installa il pacchetto

npm install @chaindoc_io/embed-sdk

L'opzione CDN è utile per prototipi rapidi o siti senza un processo di build. Per la produzione, usa il pacchetto npm così ottieni il tree-shaking e un controllo delle versioni corretto.

Configura le variabili d'ambiente

L'Embed SDK usa la tua chiave pubblica (`pk_`), che è sicura da includere nel codice client-side.

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# o per Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Inizializza nella tua 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;
}

Configurazione specifica per framework

Questi esempi mostrano come collegare l'Embed SDK come provider o servizio in ogni framework. Se stai usando il Server SDK sul backend, non hai bisogno di un provider; importalo semplicemente dove ti serve.

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

Configurazione TypeScript

Entrambi gli SDK includono definizioni TypeScript complete. Non hai bisogno di pacchetti `@types` aggiuntivi.

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

Se stai usando una configurazione TypeScript più vecchia (< 5.0), usa `"moduleResolution": "node"` invece di `"bundler"`.

Sviluppo vs produzione

Usa chiavi di test durante lo sviluppo così non crei accidentalmente documenti reali o invii email di firma a destinatari effettivi.

Configurazione sviluppo

// Usa chiavi di test per lo sviluppo
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, // Abilita log dettagliati
});

Il flag `debug: true` stampa i dettagli delle richieste/risposte nella console. È verboso, ma utile quando stai capendo perché qualcosa non funziona.

Configurazione produzione

// Usa chiavi live per la produzione
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 la tua installazione

Esegui questi controlli per assicurarti che tutto sia configurato correttamente:

Risoluzione dei problemi

Errore "Module not found"

Questo di solito significa che il pacchetto non è stato installato correttamente o c'è un conflitto di versioni in cache. Cancella tutto e reinstalla:

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

# yarn
rm -rf node_modules yarn.lock
yarn install

Errori di tipo TypeScript

Assicurati di avere i tipi Node.js installati e che il tuo `tsconfig.json` usi la giusta risoluzione dei moduli. La maggior parte dei problemi derivano da impostazioni `moduleResolution` non corrispondenti.

npm install --save-dev @types/node

Errori di chiave API

Se ricevi risposte 401 o 403, ecco cosa controllare:

• 401 Non autorizzato significa che la chiave non è valida o scaduta. Rigenerala nella tua dashboard.
• 403 Vietato significa che il tuo piano non include l'accesso API. Hai bisogno di un piano Business.
• Assicurati di usare il giusto tipo di chiave: le chiavi `pk_` sono per l'Embed SDK (frontend), le chiavi `sk_` sono per il Server SDK (backend). Confonderle è l'errore più comune.
• Le chiavi di test (`_test_`) funzionano solo contro il sandbox. Le chiavi live (`_live_`) colpiscono la produzione.

Cosa fare dopo

Ora che gli SDK sono installati, scegli il tuo prossimo passo:

• Avvio rapido — invia la tua prima richiesta di firma in 10 minuti
• Documentazione API — riferimento completo degli endpoint con esempi
• SDK — funzionalità avanzate degli SDK e guide per framework
• Webhooks — configura notifiche eventi in tempo reale
• Best practice di sicurezza — cosa configurare prima di andare live