Guida rapida

Inizia a usare Chaindoc in meno di 10 minuti. Questa guida ti accompagna sia nell'interfaccia web che nelle API, così puoi scegliere la strada che preferisci.

Firma tramite interfaccia web

Non serve codice per inviare la tua prima richiesta di firma. L'app web gestisce tutto: caricamento, destinatari, flusso di firma e verifica blockchain.

Passo dopo passo: la tua prima firma

Vuoi capire i diversi tipi di firma (semplice, avanzata, qualificata)? Questo conta per la conformità. La maggior parte dei contratti commerciali va bene con firme elettroniche semplici, ma le industrie regolamentate spesso necessitano di firme avanzate o qualificate.

Integrazione via API

Se stai integrando la firma nella tua app, userai la REST API e gli SDK TypeScript. Il flusso è lo stesso dell'interfaccia web, solo automatizzato.

1. Ottieni le tue API key

L'accesso API richiede un piano Business. Vai su Impostazioni > Accesso API nella tua dashboard e crea due key:

• Public key (`pk_`) per l'uso frontend con l'Embed SDK
• Secret key (`sk_`) per l'uso backend con il Server SDK. Tienila fuori dal codice lato client.

2. Installa l'SDK

Scegli l'SDK che corrisponde al tuo caso d'uso. La maggior parte delle app necessita di entrambi: il Server SDK per creare documenti e l'Embed SDK per l'UI di firma.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Per la configurazione specifica dei framework (React, Vue, Angular, Next.js), consulta la guida all'installazione.

3. Carica e crea un documento

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

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

Impostare `status: 'published'` attiva automaticamente la verifica blockchain. Se vuoi aspettare, usa `'draft'` e pubblica dopo.

4. Crea una richiesta di firma

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Imposta `embeddedFlow: true` se vuoi mostrare l'UI di firma dentro la tua app. Senza di esso, i firmatari ricevono un link alla pagina di firma ospitata di Chaindoc.

5. Mostra l'interfaccia di firma (frontend)

Questo è opzionale. Se hai impostato `embeddedFlow: true`, puoi aprire l'UI di firma direttamente nella tua app. Prima, crea una sessione sul backend, poi passa l'ID sessione al frontend.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Controlla lo stato e ascolta gli eventi

Puoi fare polling dello stato, ma i webhook sono un'opzione migliore per la produzione. Notificheranno il tuo server nel momento in cui succede qualcosa.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Configura i webhook (consigliato)

I webhook inviano eventi al tuo server in tempo reale, così non devi continuare a controllare. Ecco un gestore Express di base:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

In produzione, dovresti verificare le firme dei webhook con HMAC per assicurarti che il payload arrivi effettivamente da Chaindoc. La guida ai webhook copre questo in dettaglio.

Esempio di flusso completo

Questo mette tutto insieme: caricamento, creazione, firma, verifica. Copialo, inserisci le tue API key, e hai un prototipo funzionante.

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

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Dove andare dopo

Ora che hai le basi, ecco cosa approfondire a seconda di cosa stai costruendo:

• Installazione — configurazione specifica per framework per React, Vue, Angular e Next.js
• Documentazione API — riferimento completo degli endpoint con esempi di richiesta/risposta
• SDK — Server SDK e Embed SDK, con guide di integrazione per framework
• Webhook — notifiche eventi in tempo reale per app in produzione
• Best practice di sicurezza — cosa bloccare prima di andare live

Domande frequenti

Quanto dura la verifica blockchain?

Solitamente 1-5 minuti, a seconda della rete. Il tuo documento è disponibile subito però. La verifica gira in background e ricevi un evento webhook quando è completata.

Posso testare l'API senza pagare?

Il piano gratuito ti dà accesso all'interfaccia web. L'accesso API richiede un piano Business, ma l'ambiente sandbox ti permette di testare tutto senza influenzare dati reali o usare quota.

Queste firme sono legalmente valide?

Sì. Le firme Chaindoc sono conformi a eIDAS in Europa, l'ESIGN Act e UETA negli Stati Uniti, e normative equivalenti nella maggior parte delle altre giurisdizioni. La verifica blockchain aggiunge un ulteriore livello di prova, che può essere importante nelle controversie. Vedi la documentazione sulle firme per i dettagli su quale tipo di firma si adatta alle tue esigenze di conformità.

Quali formati di file posso caricare?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV e WMV. La dimensione massima del file è 50MB.