ProofSnap ProofSnap Doc API

Documentazione API ProofSnap

L'API ProofSnap apre qualsiasi URL in un browser sui server di ProofSnap e restituisce un pacchetto di prove sigillato: screenshot, HTML della pagina, metadati, un PDF delle prove e un manifest SHA-256 firmato con RSA-4096 e ancorato con OpenTimestamps. URL di base: https://api.getproofsnap.com/v1. L'autenticazione avviene con una chiave API passata come token Bearer. Documentazione aggiornata a ottobre 2026.

Gli esempi che seguono leggono l'URL di base da una variabile di shell: export PROOFSNAP_API_BASE=https://api.getproofsnap.com/v1

Primi passi

  1. 1

    Creare una chiave API

    Accedere alla Dashboard, aprire Sviluppatori, poi Chiavi API, e creare una chiave. La chiave viene mostrata una sola volta: conservarla in un luogo sicuro. Le chiavi iniziano con ps_live_ o ps_test_.

  2. 2

    Richiedere la prima acquisizione

    Passare la chiave come token Bearer. La chiamata restituisce subito 202 con un capture_id e status: "processing".

    curl -X POST "$PROOFSNAP_API_BASE/captures" \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
  3. 3

    Ottenere il risultato

    Interrogare GET /captures/{capture_id} finché status non assume il valore completed o failed. Un'acquisizione completata include package_url (un link prefirmato allo ZIP, valido fino a 24 ore) e manifest_hash. Per ottenere un nuovo link basta richiedere di nuovo l'acquisizione. In alternativa al polling, impostare in options.webhook_url un endpoint HTTPS per ricevere un evento firmato con HMAC-SHA256, capture.completed o capture.failed.

    curl "$PROOFSNAP_API_BASE/captures/cap_..." \
  -H "Authorization: Bearer ps_live_..."
  4. 4

    Verificare il pacchetto

    POST /captures/{capture_id}/verify ricontrolla ogni hash SHA-256 dichiarato e la firma RSA-4096 del manifest rispetto ai file archiviati, e restituisce match, modified o invalid. Chiunque può inoltre eseguire offline gli script della cartella verification/ del pacchetto, oppure cercare l'hash SHA-256 di manifest.json nel registro di emissione pubblico con GET /ledger/{hash}. Nessuna delle due operazioni richiede una chiave API.

    curl -X POST "$PROOFSNAP_API_BASE/captures/cap_.../verify" \
  -H "Authorization: Bearer ps_live_..."

Autenticazione

Inviare la chiave API nell'intestazione Authorization: Bearer ps_live_.... Le chiavi iniziano con ps_live_ o ps_test_. Una chiave di produzione crea acquisizioni fatturabili; una chiave di prova crea pacchetti di valutazione completi, con filigrana e non fatturati. Se non è collegato alcun account di fatturazione, una chiave di produzione funziona come una chiave di prova. Se la chiave manca, l'API restituisce 401 MISSING_API_KEY; con una chiave sconosciuta o revocata l'API restituisce 401 INVALID_API_KEY. Le chiavi del piano Website Archive sono di sola lettura (403 PLAN_API_READ_ONLY). Tre route non richiedono alcuna chiave: GET /health, GET /ledger/{hash} e GET /matter-verify.

Un nuovo account inizia in sandbox con 50 acquisizioni di prova gratuite. L'uso in modalità di prova è limitato a 200 unità per account e per giorno UTC (429 TEST_MODE_DAILY_LIMIT), i pacchetti riportano la filigrana «TEST - NOT FOR LEGAL USE» e include_eidas richiede una chiave di produzione (403 EIDAS_REQUIRES_LIVE_KEY).

Webhook

Impostare options.webhook_url per la singola richiesta, oppure creare sottoscrizioni webhook a livello di account con POST /webhook-subscriptions. Le consegne seguono il formato Standard Webhooks e includono le intestazioni webhook-id, webhook-timestamp e webhook-signature (v1, seguito da un HMAC-SHA256 calcolato su ID, timestamp e corpo con un secret whsec_). Tipi di evento: capture.completed, capture.failed, capture.anchor_confirmed, certify.completed, certify.failed, redaction.completed, redaction.failed, monitor.change_detected e schedule.paused. capture.anchor_confirmed e schedule.paused vengono inviati solo alle sottoscrizioni a livello di account. Ogni evento resta inoltre disponibile per 30 giorni in GET /events. Una consegna va in timeout dopo 10 secondi e viene ritentata dopo 5 minuti, 30 minuti, 2 ore, 8 ore e 24 ore. Quando si ruota il secret, per 24 ore le consegne vengono firmate sia con il vecchio sia con il nuovo secret.

Le consegne a un webhook_url indicato nella richiesta sono firmate con il secret di firma del webhook associato alla chiave API che ha effettuato la richiesta. Questo secret viene mostrato una sola volta, quando si crea la chiave nella sezione Sviluppatori della Dashboard. Una sottoscrizione ha un proprio secret, restituito una sola volta al momento della creazione. Verificare la firma sul corpo grezzo prima del parsing, rifiutare qualsiasi webhook-timestamp che si discosti di oltre 5 minuti dall'ora del proprio server ed elaborare ogni webhook-id una sola volta. Qualsiasi libreria Standard Webhooks gestisce questi controlli in automatico.

Limiti di frequenza ed errori

Le richieste fatturabili (POST /captures, /captures/batch, /compare, /captures/{capture_id}/redact e /certify-hash, oltre a verifiche, blocchi per controversia legale, job di esportazione e importazioni) sono limitate per account in finestre fisse di 60 secondi, condivise tra tutte le chiavi API dell'account e la sessione della Dashboard. Un batch o una certificazione di più hash consuma un'unità per URL o per hash. Unità per finestra: sandbox 10, Developer 60, Startup 120, Growth 300, Legal Solo 60, Legal Company 120, Website Archive 60, Archive only 30. Le risposte di queste route contengono le intestazioni RateLimit-Policy e RateLimit, oltre alle intestazioni legacy X-RateLimit-*; una risposta 429 include anche Retry-After.

Le acquisizioni in produzione rientrano nel limite mensile del piano (402 QUOTA_EXCEEDED); le richieste di un account con pagamenti dell'abbonamento insoluti restituiscono 402 PAYMENT_REQUIRED. Ogni account può eseguire solo un numero limitato di acquisizioni contemporaneamente (429 CONCURRENT_CAPTURE_LIMIT). Inviare un'intestazione Idempotency-Key affinché un nuovo tentativo entro 24 ore restituisca il risultato originale con Idempotent-Replay: true invece di creare una seconda acquisizione. Gli errori vengono restituiti in JSON con error.code, error.message e, se pertinente, error.details; quando si contatta l'assistenza, indicare il valore dell'intestazione di risposta X-Request-ID. L'elenco completo dei codici si trova nel riferimento qui sotto.

Endpoint in sintesi

  • Acquisizioni: POST /captures, POST /captures/batch (da 2 a 50 URL), GET /captures, GET /captures/hosts, GET /captures/{capture_id}, PATCH e DELETE /captures/{capture_id}, POST /captures/{capture_id}/verify
  • Revisione: POST /captures/{capture_id}/redact, POST /compare, POST /certify-hash (fino a 100 hash)
  • Automazione: /scheduled-captures (con /runs), /webhook-subscriptions, GET /webhook-events/{capture_id}, GET /events, GET /captures/events
  • Ambito legale: /matters (pratiche: sigillo, esportazione, condivisione), POST /legal-holds, /imports, /captures/export-jobs
  • Account e route pubbliche: GET /whoami, GET /health, GET /ledger/{hash}, GET /matter-verify

Riferimento completo

Tutti gli endpoint con parametri, risposte e schemi, generati dalla specifica OpenAPI 3. La specifica si può scaricare come openapi.json (in inglese, per i generatori di codice) oppure openapi-it.json (descrizioni in italiano). Non esiste un SDK ufficiale: generare un client con qualsiasi generatore OpenAPI 3 e verificare i webhook con qualsiasi libreria Standard Webhooks.