Guida di riferimento REST API Chaindoc

Riferimento completo degli endpoint per la REST API di Chaindoc. Copre autenticazione, documenti, firme, upload media, sessioni integrate e verifica blockchain.

Panoramica

L'API ti dà accesso programmatico a tutto ciò che c'è in Chaindoc: documenti, firme, verifica blockchain e gestione team. È progettata per uso server-to-server e supporta chiavi API pubbliche e segrete.

• Documenti — crea, aggiorna e verifica documenti sulla blockchain
• Firme — invia richieste di firma e traccia il completamento
• Media — carica PDF, immagini e video (max 10 per richiesta)
• Sessioni integrate — crea sessioni di firma per il tuo frontend (usa l'Embed SDK)
• KYC — condividi e verifica dati identità via integrazione Sumsub

Autenticazione

Ogni richiesta richiede una API key nell'header Authorization. Esistono due tipi:

Tipi di chiave

• Chiave pubblica (`pk_`) — solo lettura, sicura per il codice frontend
• Chiave segreta (`sk_`) — lettura/scrittura completa, solo backend. Non esporre mai nel codice client-side.

Come ottenere le tue chiavi

Come usare le API key

Includi la tua API key nell'header Authorization con autenticazione Bearer:

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

Limiti di richiesta

Gli endpoint API hanno limiti di richiesta per prevenire abusi. I limiti variano in base al tipo di endpoint.

• Endpoint generali: 3 richieste ogni 10 secondi
• Upload media: 3 richieste ogni 10 secondi
• Verifica OTP: 5 richieste ogni 60 secondi
• Operazioni di lettura: 10 richieste ogni 60 secondi
• Creazione firme: 20 richieste ogni 3 secondi

Quando superi il limite, riceverai una risposta 429 Too Many Requests. Gli header dei limiti sono inclusi nelle risposte:

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

Gestione errori

Codici di stato HTTP

• 200 - Success
• 201 - Resource created successfully
• 400 - Bad request (validation error)
• 401 - Unauthorized (invalid or missing API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 429 - Too many requests (rate limit exceeded)
• 500 - Internal server error

Formato risposta errore

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

API Generali

Ottieni info chiave API

Ottieni informazioni sulla API key attuale.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

Verifica connettività API e validità della chiave.

GET /health

Authorization: Bearer sk_live_xxxxx

API Documenti

Crea documento

Crea un nuovo documento con verifica blockchain. Quando lo status è impostato su 'published', 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 audit trail.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aggiorna diritti di accesso documento

Aggiorna le impostazioni di controllo accesso del documento.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Verifica documento

Verifica l'autenticità del documento usando la blockchain. Restituisce lo stato di verifica con transaction hash e chain ID.

POST /documents/verify

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

Ottieni stato verifica

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

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API Firme

Crea richiesta di firma

Crea una richiesta di firma per uno o più destinatari. Abilita il flusso integrato 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
  }'

Ottieni stato richiesta firma

Controlla lo stato di una richiesta di firma e vedi quali firmatari hanno completato la firma.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Firma documento

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

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Ottieni firme utente

Ottieni tutte le firme per l'utente autenticato.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Ottieni richieste di firma

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

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

Authorization: Bearer sk_live_xxxxx

API Upload Media

Carica file per l'uso nella creazione di documenti. Supporta 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 dati KYC

Condividi dati KYC (Know Your Customer) con destinatari per verifica identità.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API Sessioni Integrate

Crea sessioni integrate per firma documenti nella tua applicazione frontend. Le sessioni sono valide per 10 minuti.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Cosa fare dopo

• Integrazione API — pattern comuni, best practice ed esempi workflow completi
• SDK — Server SDK e Embed SDK con guide per framework specifici
• Webhook — configura notifiche eventi in tempo reale
• Installazione — setup npm per tutti i framework supportati
• Sicurezza — gestione API key e compliance