Chaindoc logoChaindoc

Integrazione API

La REST API di Chaindoc ti permette di automatizzare i flussi documentali, raccogliere firme e sincronizzare eventi in tempo reale. Ecco la cosa: questa pagina copre come iniziare, i concetti principali e i pattern più comuni.

Cosa puoi fare con l'API

L'API ti dà accesso programmatico a tutto ciò che fa Chaindoc: caricare documenti, creare richieste di firma, gestire team e ascoltare eventi via webhook. È la stessa API che alimenta l'app web.

Tre modalità di integrazione

Scegli quella più adatta al tuo stack. In pratica, la maggior parte delle app in produzione usa il Server SDK sul backend e l'Embed SDK sul frontend.

  • REST API — chiamate HTTP dirette, funziona con qualsiasi linguaggio. Massima flessibilità.
  • Server SDK — wrapper TypeScript per Node.js con retry automatici e gestione errori (`@chaindoc_io/server-sdk`)
  • Embed SDK — inserisce un'interfaccia di firma nella tua web app così gli utenti non lasciano il sito (`@chaindoc_io/embed-sdk`)

Se non hai ancora installato gli SDK, la guida all'installazione copre la configurazione npm per React, Vue, Angular e Next.js.

Esempio rapido

La stessa chiamata "crea documento" in tre varianti. La versione SDK è la più concisa, ma la chiamata REST raw mostra esattamente cosa succede sul filo.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Autenticazione

Ogni richiesta richiede una API key nell'header Authorization:

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Esistono due tipi di chiavi, onestamente, confonderle è l'errore di integrazione più comune:

  • Chiavi pubbliche (`pk_`) — sola lettura, sicure per il codice frontend
  • Chiavi segrete (`sk_`) — lettura/scrittura complete, solo backend. Non esporle mai nel codice client.
  • Entrambe vengono in varianti test (`_test_`) e live (`_live_`). Le chiavi test colpiscono il sandbox.

Rate limit

L'API restituisce informazioni sul rate limit negli header di risposta. Se superi il limite, ricevi una risposta 429. Aspetta e riprova.

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • Endpoint generali: 3 richieste ogni 10 secondi
  • Caricamento media: 3 richieste ogni 10 secondi
  • Operazioni di lettura: 10 richieste ogni 60 secondi
  • Creazione firme: 20 richieste ogni 3 secondi

Il Server SDK gestisce i retry automaticamente con backoff esponenziale. Se usi HTTP raw, implementa tu la logica di retry.

Gestione errori

Gli errori tornano come JSON con codice di stato, messaggio e (per errori di validazione) un elenco di problemi specifici per campo:

terminal
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Codici di stato comuni: 400 (richiesta errata), 401 (chiave non valida), 403 (il piano non include API), 404 (non trovato), 429 (rate limit), 500 (errore server). Per errori 5xx, riprova con backoff.

Pattern di integrazione comuni

Flusso di firma completo (embedded)

Il pattern più diffuso: carichi un documento, lo invii per le firme e mostri l'interfaccia di firma dentro la tua app.

1Carica il filePOST /media/upload — invia il PDF, documento Office o immagine.

2Crea il documentoPOST /documents — imposta status='published' per attivare la verifica blockchain.

3Crea una richiesta di firmaPOST /signatures/requests — aggiungi destinatari, imposta ordine di firma e scadenza.

4Crea una sessione embeddedPOST /embedded/sessions — ottieni un sessionId per ogni firmatario.

5Apri l'interfaccia di firmaPassa il sessionId al metodo openSignatureFlow() dell'Embed SDK.

6Ascolta il completamentoConfigura un webhook per l'evento signature.request.completed, o fai polling su GET /signatures/requests/:id/status.

La guida quick start ha il codice completo per questo flusso.

Firma via email (senza embed)

Se i firmatari non usano la tua app, imposta `embeddedFlow: false`. Chaindoc invia loro un'email con link di firma. Ricevi comunque le notifiche webhook quando firmano.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // I firmatari ricevono link via email
  message: 'Please review and sign this document',
});

Elaborazione documenti in batch

Per importazioni batch, cicla i tuoi file e carica ognuno. Attenzione ai rate limit però. Se elabori centinaia di documenti, aggiungi una piccola pausa tra le richieste o usa la logica di retry integrata nell'SDK.

terminal
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Integrazione KYC

Per workflow ad alta sicurezza, richiedi la verifica dell'identità prima della firma. Chaindoc si integra con Sumsub per KYC. Imposta `isKycRequired: true` sulla richiesta di firma, e i firmatari passeranno attraverso la verifica identità prima di poter firmare.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Opzionale: pre-verificato
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Controllo accessi via API

Puoi impostare i permessi documentali programmaticamente. Limita l'accesso a email specifiche o ruoli team:

terminal
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Best practice

  • Tieni le API key nelle variabili d'ambiente. Non committarle mai nel version control.
  • Usa chiavi test (`sk_test_`) per lo sviluppo. Le chiavi live (`sk_live_`) colpiscono la produzione.
  • Implementa backoff esponenziale per risposte 429. L'SDK lo fa automaticamente.
  • Verifica le firme dei webhook con HMAC per prevenire attacchi replay.
  • Carica i file prima di creare i documenti. L'API ha bisogno dell'ID media dallo step di upload.
  • Usa la paginazione per endpoint che restituiscono liste. Non recuperare tutto in una volta.
  • Controlla la guida sicurezza prima di andare live.

Esempi di casi d'uso

L'essenziale: alcuni pattern reali che i team costruiscono con l'API.

  • E-commerce — genera automaticamente contratti d'acquisto per ordini di valore elevato e inviali per firma al checkout
  • HR onboarding — crea contratti di lavoro da template e inviali ai nuovi assunti il giorno di inizio
  • Integrazione CRM — attiva richieste di firma dai record deal di Salesforce o HubSpot
  • Archiviazione documenti — aggiungi verifica blockchain ai documenti nel tuo sistema di storage esistente

Cosa fare dopo

  • Documentazione API — riferimento completo endpoint con esempi request/response
  • SDK — Server SDK e Embed SDK con guide specifiche per framework
  • Webhook — configura notifiche eventi in tempo reale
  • Quick start — fai funzionare la tua prima integrazione in 10 minuti
  • Installazione — setup npm per tutti i framework supportati