Chaindoc logoChaindoc

Riferimento API REST Chaindoc

Riferimento completo per integrare l'API REST di Chaindoc nelle tue app. Gestisci documenti, firme, verifica blockchain e flussi di lavoro di firma incorporati.

Panoramica

L'API REST di Chaindoc ti dà accesso programmatico alla gestione dei documenti, alla verifica della blockchain e alla firma digitale. L'API è fatta per l'integrazione da server a server e funziona sia con chiavi API pubbliche che private.

Caratteristiche principali

  • Gestione dei documenti: crea, aggiorna e gestisci i documenti con la verifica blockchain.
  • Firme digitali: chiedi e raccogli le firme digitali da più parti.
  • Verifica blockchain: controlla che i documenti siano autentici sulle reti blockchain.
  • Sessioni incorporate: crea sessioni sicure per i flussi di lavoro di firma front-end.
  • Caricamento multimediale - Carica file (PDF, immagini, video) per creare documenti
  • Integrazione KYC - Condividi e verifica i dati di identità con Sumsub

Autenticazione

L'API Chaindoc usa delle chiavi API per l'autenticazione. Ci sono due tipi di chiavi con livelli di accesso diversi.

Tipi di chiavi API

  • Chiave pubblica (pk_) - Accesso in sola lettura per le app frontend e la verifica
  • Chiave segreta (sk_) - Accesso completo in lettura e scrittura per i server backend

Ottenere le chiavi API

1Iscriviti al Business PlanSolo chi ha un piano Business può creare chiavi API.

2Vai su Accesso APIVai su Impostazioni → Accesso API nella tua dashboard

3Crea chiave APIClicca sul pulsante Crea chiave API

4Conserva in modo sicuroTieni al sicuro la chiave segreta (mostrata solo una volta)

Uso delle chiavi API

Includi la tua chiave API nell'intestazione di autorizzazione con autenticazione Bearer:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Limitazione della velocità

Gli endpoint API hanno dei limiti di velocità per evitare abusi. I limiti di velocità variano a seconda del tipo di endpoint.

  • Limiti generali: 3 richieste ogni 10 secondi
  • Caricamento di file multimediali: 3 richieste ogni 10 secondi
  • Verifica OTP: 5 richieste ogni 60 secondi
  • Operazioni di lettura: 10 richieste ogni 60 secondi
  • Creazione della firma: 20 richieste ogni 3 secondi

Quando superi il limite di velocità, riceverai una risposta 429 Too Many Requests. Le intestazioni del limite di velocità sono incluse nelle risposte:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Gestione degli errori

Codici di stato HTTP

  • 200 - Successo
  • 201 - Risorsa creata con successo
  • 400 - Richiesta non valida (errore di convalida)
  • 401 - Non autorizzato (chiave API non valida o mancante)
  • 403 - Vietato (permessi insufficienti)
  • 404 - Risorsa non trovata
  • 429 - Troppe richieste (limite di frequenza superato)
  • 500 - Errore interno del server

Formato di risposta di errore

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

API generale

Ottieni le informazioni sulla chiave API

Ottieni informazioni sulla chiave API attuale.

GET /me

Authorization: Bearer sk_live_xxxxx

Controllo di integrità

Controlla che l'API funzioni e che le chiavi siano valide.

GET /health

Authorization: Bearer sk_live_xxxxx

API dei documenti

Crea documento

Crea un nuovo documento con verifica blockchain. Quando lo stato è impostato su "pubblicato", il documento viene automaticamente verificato sulla blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aggiorna documento

Aggiorna un documento creando una nuova versione. Le versioni precedenti vengono conservate per la tracciabilità dei controlli.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aggiorna i diritti di accesso al documento

Aggiorna le impostazioni di controllo dell'accesso ai documenti.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Controlla il documento

Controlla se il documento è autentico usando la blockchain. Ti dice se è ok con l'hash della transazione e l'ID della catena.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Ottieni lo stato di verifica

Ottieni lo stato di verifica blockchain per una versione del documento.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API delle firme

Crea richiesta di firma

Crea una richiesta di firma per uno o più destinatari. Attiva il flusso incorporato per l'integrazione frontend.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Controlla lo stato della richiesta di firma

Controlla lo stato di una richiesta di firma e vedi quali firmatari hanno finito di firmare.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Firma il documento

Firma un documento (se il proprietario della chiave API è un firmatario).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Ottieni le firme degli utenti

Prendi tutte le firme per l'utente autenticato.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Ricevi richieste di firma

Ottieni tutte le richieste di firma per l'utente autenticato con supporto per l'impaginazione.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API per il caricamento di file multimediali

Carica i file da usare per creare documenti. Puoi usare PDF, immagini e video. Massimo 10 file per richiesta.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

API KYC

Condividi i dati KYC

Condividi i dati KYC (Know Your Customer) con i destinatari per la verifica dell'identità.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API delle sessioni incorporate

Crea sessioni integrate per la firma dei documenti nella tua app frontend. Le sessioni durano 10 minuti.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json