REST · JSON · kein separater Host

Proovik-API

Weisen Sie aus Ihrem eigenen Code nach, dass Ihr Dokument zu einem bestimmten Datum und einer bestimmten Uhrzeit bereits existierte. Es ist dieselbe API, die diese Website nutzt: Alle Endpoints dieser Seite existieren heute und antworten in der Produktion.

Basis-URL https://proovik.com/api

Authentifizierung · Header Authorization: Bearer IHR_API_KEY bei den mit „Schlüssel“ markierten Endpoints. Die mit „öffentlich“ markierten brauchen keinen Schlüssel.

So erhalten Sie heute einen API-Schlüssel

Es gibt noch keine Selbstbedienung. Proovik schaltet den Schlüssel manuell für Ihr Konto frei; sobald er aktiv ist, erscheint er in Ihrem Dashboard im Bereich API. Ein einziger Schlüssel gilt für Zertifizierung und Rückverfolgbarkeit.

Erstellen Sie ein Konto (kostenlos).
Beantragen Sie die API-Freischaltung über das Kontaktformular, Betreff „API“, mit der E-Mail-Adresse Ihres Kontos und dem geplanten Verwendungszweck.
Sobald der Schlüssel aktiv ist, kopieren Sie ihn aus dem Dashboard. Erscheint er noch nicht, wurde der Antrag noch nicht bearbeitet: einen anderen Weg gibt es nicht.

Freischaltung beantragen Mein Dashboard öffnen

Zertifizierung von Dokumenten

Verankerung des SHA-256 einer Datei in der Kaspa-Chain

Das Dokument wird nie übertragen: Sie berechnen den SHA-256 in Ihrem eigenen System und senden nur den Hashwert (64 hexadezimale Zeichen).

POST/api/certifySchlüsselEinen Hashwert zertifizieren

Verankert den Hashwert in der Chain. Verbraucht ein Guthaben Ihres Kontos. War derselbe Hashwert bereits zertifiziert, wird der vorhandene Eintrag zurückgegeben (already_exists: true), ohne etwas zu verbrauchen.

Anfrage

curl -X POST https://proovik.com/api/certify \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "description": "Contrato v2.1"
  }'

Antwort · 200 · bestätigt

{
  "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 · gesendet und ausstehend. Die Transaktion ist bereits übertragen, aber noch nicht sichtbar: Senden Sie denselben Hashwert nach einigen Sekunden erneut, um den Endzustand zu erhalten (es gibt keinen Webhook, der Sie benachrichtigt).

Fehler: 400 invalid_hash · 401 invalid_api_key · 401 identification_required (ohne Schlüssel bleibt der Endpoint dem Webformular vorbehalten) · 429 no_credits · 502 notary_failed (es wird nichts berechnet).

GET/api/verify?hash={sha256}öffentlichPrüfen, ob ein Hashwert zertifiziert ist

Jeder kann das ohne Schlüssel abfragen. Zurückgegeben werden nur in der Chain bestätigte Zertifizierungen.

Anfrage

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

Antwort

{
  "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}öffentlichDas PDF-Zertifikat herunterladen

Die Antwort von /api/certify enthält certificate_url: einen signierten Link (Parameter t), der auch Ihre privaten Metadaten zeigt. Ohne t liefert derselbe Endpoint jedem die öffentliche Fassung des Zertifikats. Dem PDF liegt das Nachweispaket PVK-PROOF/1 bei, das sich ohne Proovik prüfen lässt.

Anfrage

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

Fehler: 404 not_found · 409 certification_pending (JSON, kein PDF: es gibt noch kein Zertifikat) · 429 rate_limited (60 Downloads pro Stunde und IP).

GET/api/certify/proof?hash={sha256}SchlüsselMerkle-Nachweis einer Zertifizierung

Gibt den Merkle-Pfad und die verankerte Wurzel einer mit Ihrem Schlüssel erstellten Zertifizierung zurück. Für andere Konten antwortet der Endpoint mit 404.

Anfrage

curl "https://proovik.com/api/certify/proof?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "Authorization: Bearer IHR_API_KEY"

Antwort

{
  "success": true,
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "status": "success",
  "txid": "b173e1ff…802889",
  "anchored": true,
  "merkle_root": "d4735e3a…13ab35",
  "merkle_proof": [ { "hash": "…", "position": "left" }, … ]
}

Rückverfolgbarkeit von Chargen

Chargen und Ereignisse per Hash verkettet und in Merkle-Batches verankert

Jedes Ereignis verweist auf den Hashwert des vorherigen; das erste verweist auf den Hashwert der Charge. Die Einträge werden in Zyklen von wenigen Minuten in der Kaspa-Chain verankert: Der Status wechselt von pending zu confirmed, ohne dass Sie etwas tun müssen. GS1-Kennungen (GTIN, SGTIN, GLN) werden per Prüfziffer validiert.

POST/api/trace/batchSchlüsselEine Charge anlegen

Pflichtfeld: product_name. Optional: batch_id (wird sonst erzeugt), gtin, sgtin (systemweit eindeutig; eine Wiederholung antwortet mit 409), origin, origin_gln, origin_lat/origin_lng, quantity, quantity_unit, metadata. Unterstützt den Header Idempotency-Key.

Anfrage

curl -X POST https://proovik.com/api/trace/batch \
  -H "Authorization: Bearer IHR_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 }
  }'

Antwort · 201

{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "payload_hash": "7f83b165…6d9069",
  "created_at": "2026-09-05T10:00:00+00:00"
}

POST/api/trace/eventSchlüsselEin Ereignis hinzufügen

Pflichtfelder: batch_id und event_type, eines von COMMISSION, OBSERVE, TRANSFORM, SHIP, RECEIVE, AGGREGATE, DISAGGREGATE, CUSTOM. Optional: location {name, gln, lat, lng}, actor {name, id, role}, data, evidence_hash, gs1_bizstep.

Anfrage

curl -X POST https://proovik.com/api/trace/event \
  -H "Authorization: Bearer IHR_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 }
  }'

Antwort · 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}Schlüssel optionalEine Charge mit ihren Ereignissen lesen

Ohne Schlüssel erhalten Sie die öffentliche Ansicht der Charge; mit Ihrem Schlüssel die vollständigen Daten Ihrer eigenen Chargen.

Anfrage

curl "https://proovik.com/api/trace/batch/BATCH-20260905-A1B2C3D4" \
  -H "Authorization: Bearer IHR_API_KEY"

GET/api/trace/verify/{batch_id}Schlüssel optionalDie Integrität einer Charge prüfen

Berechnet den Hashwert der Charge, die Ereigniskette und die Merkle-Nachweise gegen das Verankerte neu. overall_valid ist nur dann true, wenn alles zusammenpasst; fully_verified verlangt zusätzlich, dass alle Ereignisse bestätigt sind.

Anfrage

curl "https://proovik.com/api/trace/verify/BATCH-20260905-A1B2C3D4"

Antwort

{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "verification": {
    "overall_valid": true,
    "batch_integrity": { "valid": true, … },
    "chain_integrity": { "valid": true, … },
    "fully_verified": true
  }
}

Ebenfalls vorhanden, mit Schlüssel: 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 und GET /api/trace/batch/{batch_id}/qr. Details in der vollständigen Referenz.

Limits pro Schlüssel: 60 Schreib- und 300 Lesevorgänge pro Minute. Bei Überschreitung antwortet die API mit 429 und Retry-After.

Unabhängige Prüfung (PVK-PROOF/1)

Einen Nachweis prüfen, ohne Proovik vertrauen zu müssen

Der Verifizierer berechnet die vier Glieder des Nachweises neu: Der Hashwert des Dokuments steht in der Transaktion, die Transaktion steht im Merkle-Baum des Blocks, der Header reproduziert den Blockhash, und dieser Header trägt einen gültigen Arbeitsnachweis. Den Hashwert des Dokuments liefern immer Sie selbst: Er wird nie aus dem Paket gelesen. Drei Urteile: VALIDO, INCOMPLETO (nicht feststellbar; gilt nie als gültig) und INVALIDO.

POST/api/verify/prooföffentlichEin Nachweispaket prüfen

Senden Sie die Datei .pvkproof.json (die dem PDF beiliegt) oder das Paket als JSON zusammen mit dem SHA-256 Ihrer Kopie des Dokuments. Es wird nichts im Netz abgefragt: geprüft wird, was Sie übergeben. Ohne Schlüssel.

Anfrage

curl -X POST https://proovik.com/api/verify/proof \
  -F "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -F "[email protected]"

Antwort

{
  "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}öffentlichAus der Chain rekonstruieren und prüfen

Allein mit txid und Hashwert rekonstruiert der Endpoint das Paket über eine Abfrage im Kaspa-Netz. Der vollständige Block-Header ist nur etwa 40 Stunden verfügbar: danach bleiben die Glieder 3 und 4 INCOMPLETO. Ohne Schlüssel; CORS offen; 30 Anfragen pro Stunde und IP.

Anfrage

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

Spezifikation und Online-Prüfer

Was diese API (noch) nicht hat

Ausgehende Webhooks. Nichts benachrichtigt Sie, wenn eine Transaktion bestätigt wird. Für Zertifizierungen senden Sie denselben Hashwert erneut an POST /api/certify oder fragen GET /api/verify?hash= ab; für die Rückverfolgbarkeit fragen Sie GET /api/trace/verify/{batch_id} ab.
SDKs. Es gibt in keiner Sprache offizielle Bibliotheken. Es ist HTTP und JSON: Jeder HTTP-Client genügt.
OpenAPI-Datei. Die Referenz der Felder und Antworten steht in der unten verlinkten technischen Dokumentation.
Selbstbedienungs-Schlüssel, mehrere Schlüssel oder Scopes. Ein Schlüssel pro Konto, manuell freigeschaltet.
Testumgebung. Jede echte Zertifizierung verbraucht ein Guthaben. Zum kostenlosen Ausprobieren nutzen Sie die öffentlichen Abfrage- und Prüf-Endpoints.

PVK-PROOF/1

Vollständige Referenz und Prüfer

Die technische Dokumentation beschreibt alle Felder und Antworten (vorerst nur auf Spanisch). Der Online-Prüfer prüft jedes Zertifikat ohne Konto.

Technische Dokumentation Online-Prüfer API-Schlüssel anfordern