Integrazione API

Metti Chaindoc nelle tue app con la nostra API REST e gli SDK. Fai in modo che i documenti si muovano da soli, prendi le firme e sincronizza gli eventi in tempo reale.

Panoramica

Chaindoc offre un'API REST completa che ti permette di creare flussi di lavoro personalizzati per la firma dei documenti, automatizzare i processi e integrarli con i tuoi sistemi esistenti. L'API è pensata per gli sviluppatori con supporto completo TypeScript e riprova automatica.

Per iniziare

1. Ottieni l'accesso all'API

2. Scegli il metodo di integrazione

Chaindoc offre tre modi per integrarlo:

• API REST - Richieste HTTP dirette per la massima flessibilità
• Server SDK - SDK Node.js con sicurezza dei tipi e tentativi automatici (@chaindoc_io/server-sdk)
• SDK incorporato - Interfaccia di firma frontend per app web (@chaindoc_io/embed-sdk)

3. Esempio veloce

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": []
  }'

Concetti fondamentali dell'API

Autenticazione

Tutte le richieste API richiedono l'autenticazione utilizzando le chiavi API nell'intestazione Authorization:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Chiavi pubbliche (pk_) - Accesso in sola lettura per le app frontend
• Chiavi segrete (sk_) - Accesso completo in lettura/scrittura per i server backend
• Chiavi di test (pk_test_, sk_test_) - Per staging/sviluppo
• Live Keys (pk_live_, sk_live_) - Per la produzione

Limiti di velocità

Gli endpoint API hanno dei limiti di velocità per garantire un uso corretto:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Limiti generali: 3 richieste ogni 10 secondi
• Caricamento multimediale: 3 richieste ogni 10 secondi
• Operazioni di lettura: 10 richieste ogni 60 secondi
• Creazione della firma: 20 richieste ogni 3 secondi

Gestione degli errori

L'API restituisce codici di stato HTTP standard con messaggi di errore dettagliati:

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

Modelli di integrazione comuni

Caricamento dei documenti e flusso di firma

Flusso di lavoro solo backend

Per i casi in cui chi firma non usa la tua interfaccia:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Elaborazione di documenti in blocco

// Process multiple documents in batch
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' }],
  });
}

Funzioni avanzate

Webhook

Ricevi notifiche in tempo reale sugli eventi relativi ai documenti:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Integrazione KYC

Aggiungi la verifica dell'identità per i flussi di lavoro ad alta sicurezza:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Controllo degli accessi

Gestisci i permessi dei documenti con un controllo granulare degli accessi:

// Update document access rights
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' }, // Team role
  ],
});

Buone pratiche

• Metti le chiavi API nelle variabili d'ambiente, mai nel codice
• Usa le chiavi di prova per lo sviluppo e quelle live per la produzione.
• Usa il backoff esponenziale per gestire i limiti di velocità.
• Controlla le firme dei webhook per evitare attacchi di replay.
• Metti in cache le risposte API quando serve
• Carica i file prima di creare i documenti per avere prestazioni migliori
• Usa l'impaginazione per i set di dati grandi
• Tieni d'occhio le intestazioni dei limiti di velocità e regola la frequenza delle richieste

Esempi di integrazioni

Piattaforma di e-commerce

Genera e firma automaticamente i contratti di acquisto per gli ordini di alto valore.

Sistema HR

Integra con HRIS per firmare automaticamente i contratti di lavoro durante l'onboarding.

Integrazione CRM

Crea richieste di firma direttamente dai record dei clienti in Salesforce, HubSpot o CRM personalizzati.

Sistema di gestione dei documenti

Aggiungi la verifica blockchain al DMS che già hai per avere tracce di audit a prova di manomissione.

Risorse

• Documentazione API - Riferimento completo all'API REST con tutti gli endpoint
• SDK - Documentazione SDK server e SDK incorporato con esempi di framework
• Webhook - Guida per impostare le notifiche degli eventi in tempo reale
• Avvio rapido: fai funzionare la tua prima integrazione in 10 minuti
• Esempi GitHub - Esempi di integrazioni e frammenti di codice