Proovik
Certificare
REST · JSON · senza host separato

API di Proovik

Dimostra dal tuo codice che il tuo documento esisteva già a una data e a un'ora precise. È la stessa API che usa questo sito: tutti gli endpoint di questa pagina esistono oggi e rispondono in produzione.

URL di base https://proovik.com/api

Autenticazione · Header Authorization: Bearer TUA_API_KEY negli endpoint contrassegnati con «chiave». Quelli contrassegnati «pubblico» non richiedono chiave.

Come ottenere oggi la chiave API

Non è ancora self-service. Proovik attiva la chiave a mano per il tuo account e, una volta attiva, compare nel tuo pannello, nella sezione API. Un'unica chiave vale per certificazione e tracciabilità.

  1. Crea un account (gratis).
  2. Richiedi l'attivazione dell'API dal modulo di contatto, oggetto «API», indicando l'e-mail del tuo account e l'uso che ne farai.
  3. Quando è attiva, copia la chiave dal pannello. Se non compare ancora, la richiesta non è stata elaborata: non c'è un'altra strada.
Richiedere l'attivazione Vai al mio pannello

Certificazione di documenti

Ancoraggio dello SHA-256 di un file sulla catena di Kaspa

Il documento non viene mai inviato: calcoli il suo SHA-256 sul tuo sistema e mandi solo l'hash (64 caratteri esadecimali).

POST/api/certifychiaveCertificare un hash

Registra l'hash sulla catena. Consuma un credito del tuo account. Se lo stesso hash era già certificato, restituisce il record esistente (already_exists: true) senza consumare nulla.

Richiesta
curl -X POST https://proovik.com/api/certify \
  -H "Authorization: Bearer TUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "description": "Contrato v2.1"
  }'
Risposta · 200 · confermata
{
  "success": true,
  "status": "success",
  "confirmed": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "credit_consumed": true,
  "certificate_url": "/api/certificate?hash=e3b0c442…&t=…"
}
202 · inviata e in attesa. La transazione è già trasmessa ma non ancora visibile: reinvia lo stesso hash dopo qualche secondo per ottenere lo stato finale (non c'è un webhook che ti avvisa).

Errori: 400 invalid_hash · 401 invalid_api_key · 401 identification_required (senza chiave l'endpoint resta riservato al modulo web) · 429 no_credits · 502 notary_failed (non viene addebitato nulla).

GET/api/verify?hash={sha256}pubblicoVerificare se un hash è certificato

Chiunque può consultarlo, senza chiave. Restituisce solo certificazioni confermate sulla catena.

Richiesta
curl "https://proovik.com/api/verify?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Risposta
{
  "success": true,
  "exists": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "explorer_url": "https://explorer.kaspa.org/txs/b173e1ff…802889",
  "timestamp": "2026-01-12 20:48:30",
  "has_merkle_proof": true
}
// {"success": true, "exists": false}  si no está certificado
GET/api/certificate?hash={sha256}&t={token}pubblicoScaricare il certificato PDF

La risposta di /api/certify include certificate_url: un link firmato (parametro t) che mostra anche i tuoi metadati privati. Senza t lo stesso endpoint serve a chiunque la versione pubblica del certificato. Al PDF è allegato il pacchetto di prova PVK-PROOF/1, verificabile senza Proovik.

Richiesta
curl -o certificado.pdf \
  "https://proovik.com/api/certificate?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Errori: 404 not_found · 409 certification_pending (JSON, non PDF: il certificato non esiste ancora) · 429 rate_limited (60 download per ora e IP).

GET/api/certify/proof?hash={sha256}chiaveProva Merkle di una certificazione

Restituisce il percorso Merkle e la radice ancorata di una certificazione fatta con la tua chiave. Quelle di altri account rispondono 404.

Richiesta
curl "https://proovik.com/api/certify/proof?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "Authorization: Bearer TUA_API_KEY"
Risposta
{
  "success": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "status": "success",
  "txid": "b173e1ff…802889",
  "anchored": true,
  "merkle_root": "d4735e3a…13ab35",
  "merkle_proof": [ { "hash": "…", "position": "left" }, … ]
}

Tracciabilità dei lotti

Lotti ed eventi concatenati tramite hash e ancorati in batch Merkle

Ogni evento si collega all'hash del precedente; il primo si collega all'hash del lotto. I record vengono ancorati alla catena di Kaspa in cicli di pochi minuti: lo stato passa da pending a confirmed senza che tu debba fare nulla. Identificatori GS1 (GTIN, SGTIN, GLN) validati con cifra di controllo.

POST/api/trace/batchchiaveCreare un lotto

Obbligatorio: product_name. Facoltativi: batch_id (altrimenti viene generato), gtin, sgtin (unico in tutto il sistema; se ripetuto risponde 409), origin, origin_gln, origin_lat/origin_lng, quantity, quantity_unit, metadata. Accetta l'header Idempotency-Key.

Richiesta
curl -X POST https://proovik.com/api/trace/batch \
  -H "Authorization: Bearer TUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Aceite de oliva virgen extra 500 ml",
    "gtin": "8412345678905",
    "origin": "Jaén",
    "quantity": 5000,
    "quantity_unit": "bottles",
    "metadata": { "variety": "Picual", "harvest_year": 2025 }
  }'
Risposta · 201
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "payload_hash": "7f83b165…6d9069",
  "created_at": "2026-09-05T10:00:00+00:00"
}
POST/api/trace/eventchiaveAggiungere un evento

Obbligatori: batch_id e event_type, uno tra COMMISSION, OBSERVE, TRANSFORM, SHIP, RECEIVE, AGGREGATE, DISAGGREGATE, CUSTOM. Facoltativi: location {name, gln, lat, lng}, actor {name, id, role}, data, evidence_hash, gs1_bizstep.

Richiesta
curl -X POST https://proovik.com/api/trace/event \
  -H "Authorization: Bearer TUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "BATCH-20260905-A1B2C3D4",
    "event_type": "SHIP",
    "location": { "name": "Almacén central", "gln": "8412345000010" },
    "data": { "carrier": "Transportes Sur", "pallets": 12 }
  }'
Risposta · 201
{
  "success": true,
  "event_id": 17,
  "sequence": 3,
  "event_hash": "e3b0c442…52b855",
  "prev_event_hash": "9f86d081…00a08",
  "status": "pending"
}
GET/api/trace/batch/{batch_id}chiave facoltativaLeggere un lotto con i suoi eventi

Senza chiave restituisce la vista pubblica del lotto; con la tua chiave, i dati completi dei tuoi lotti.

Richiesta
curl "https://proovik.com/api/trace/batch/BATCH-20260905-A1B2C3D4" \
  -H "Authorization: Bearer TUA_API_KEY"
GET/api/trace/verify/{batch_id}chiave facoltativaVerificare l'integrità di un lotto

Ricalcola l'hash del lotto, la catena di eventi e le prove Merkle rispetto a quanto ancorato. overall_valid è true solo se tutto torna; fully_verified richiede inoltre che tutti gli eventi siano confermati.

Richiesta
curl "https://proovik.com/api/trace/verify/BATCH-20260905-A1B2C3D4"
Risposta
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "verification": {
    "overall_valid": true,
    "batch_integrity": { "valid": true, … },
    "chain_integrity": { "valid": true, … },
    "fully_verified": true
  }
}

Esistono anche, con chiave: GET /api/trace/search?gtin=|sgtin=|lot=|product=, GET /api/trace/event/{event_id}, GET /api/trace/event/{event_id}/proof, GET /api/trace/batch/{batch_id}/proof e GET /api/trace/batch/{batch_id}/qr. Dettagli nel riferimento completo.

Limiti per chiave: 60 scritture e 300 letture al minuto. Superandoli risponde 429 con Retry-After.

Verifica indipendente (PVK-PROOF/1)

Controllare una prova senza fidarsi di Proovik

Il verificatore ricalcola i quattro anelli della prova: l'hash del documento è nella transazione, la transazione è nell'albero Merkle del blocco, l'intestazione riproduce l'hash del blocco e quell'intestazione ha una prova di lavoro valida. L'hash del documento lo fornisci sempre tu: non viene mai letto dal pacchetto. Tre verdetti: VALIDO, INCOMPLETO (non determinabile; non vale mai come valido) e INVALIDO.

POST/api/verify/proofpubblicoVerificare un pacchetto di prova

Invia il file .pvkproof.json (quello allegato al PDF) o il pacchetto in JSON, insieme allo SHA-256 della tua copia del documento. Non interroga la rete: verifica ciò che gli passi. Senza chiave.

Richiesta
curl -X POST https://proovik.com/api/verify/proof \
  -F "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -F "[email protected]"
Risposta
{
  "spec": "PVK-PROOF/1",
  "modo": "paquete",
  "documento_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "txid": "b173e1ff…802889",
  "resultado": "VALIDO",
  "valido": true,
  "completo": true,
  "eslabones": [
    { "n": 1, "estado": "OK", … },
    { "n": 2, "estado": "OK", … },
    { "n": 3, "estado": "OK", … },
    { "n": 4, "estado": "OK", … }
  ],
  "algoritmo": { … }
}
GET/api/verify/proof/{txid}?hash={sha256}pubblicoRicostruire e verificare dalla catena

Con il solo txid e l'hash, ricostruisce il pacchetto interrogando la rete Kaspa. L'intestazione completa del blocco è disponibile solo per circa 40 ore: trascorso quel termine gli anelli 3 e 4 restano INCOMPLETO. Senza chiave; con CORS aperto; 30 richieste per ora e IP.

Richiesta
curl "https://proovik.com/api/verify/proof/b173e1ff9d73e09b51db78b9050a4be578f232f3d5e106a214950a8265802889?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Specifica e verificatore online

Ciò che questa API non ha (ancora)

  • Webhook in uscita. Nulla ti avvisa quando una transazione viene confermata. Per le certificazioni, reinvia lo stesso hash a POST /api/certify oppure interroga GET /api/verify?hash=; per la tracciabilità, interroga GET /api/trace/verify/{batch_id}.
  • SDK. Non esistono librerie ufficiali in nessun linguaggio. È HTTP e JSON: va bene qualsiasi client HTTP.
  • File OpenAPI. Il riferimento di campi e risposte si trova nella documentazione tecnica collegata sotto.
  • Chiavi self-service, chiavi multiple o scope. Una chiave per account, attivata a mano.
  • Ambiente di test. Ogni certificazione reale consuma un credito. Per provare senza spendere, usa gli endpoint pubblici di consultazione e verifica.
PVK-PROOF/1

Riferimento completo e verificatore

La documentazione tecnica descrive tutti i campi e le risposte (per ora solo in spagnolo). Il verificatore online controlla qualsiasi certificato senza account.

Documentazione tecnica Verificatore online Richiedere la chiave API