Proovik
Certifier
REST · JSON · sans hôte séparé

API de Proovik

Prouve depuis ton propre code que ton document existait déjà à une date et une heure précises. C'est la même API qu'utilise ce site : tous les endpoints de cette page existent aujourd'hui et répondent en production.

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

Authentification · En-tête Authorization: Bearer VOTRE_API_KEY sur les endpoints marqués « clé ». Ceux marqués « public » n'ont besoin d'aucune clé.

Comment obtenir une clé d'API aujourd'hui

Ce n'est pas encore du libre-service. Proovik active la clé à la main pour ton compte et, une fois active, elle apparaît dans ton tableau de bord, section API. Une seule clé sert pour la certification et la traçabilité.

  1. Crée un compte (gratuit).
  2. Demande l'activation de l'API depuis le formulaire de contact, objet « API », en indiquant l'e-mail de ton compte et l'usage prévu.
  3. Une fois active, copie la clé depuis le tableau de bord. Si elle n'y est pas encore, la demande n'a pas été traitée : il n'y a pas d'autre voie.
Demander l'activation Voir mon tableau de bord

Certification de documents

Ancrage du SHA-256 d'un fichier dans la chaîne Kaspa

Le document n'est jamais envoyé : tu calcules son SHA-256 sur ton système et tu n'envoies que le hash (64 caractères hexadécimaux).

POST/api/certifycléCertifier un hash

Ancre le hash dans la chaîne. Consomme un crédit de ton compte. Si le même hash était déjà certifié, l'enregistrement existant est renvoyé (already_exists: true) sans rien consommer.

Requête
curl -X POST https://proovik.com/api/certify \
  -H "Authorization: Bearer VOTRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "description": "Contrato v2.1"
  }'
Réponse · 200 · confirmée
{
  "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 · envoyée et en attente. La transaction est déjà diffusée mais pas encore visible : renvoie le même hash après quelques secondes pour obtenir l'état final (aucun webhook ne te prévient).

Erreurs: 400 invalid_hash · 401 invalid_api_key · 401 identification_required (sans clé, l'endpoint est réservé au formulaire web) · 429 no_credits · 502 notary_failed (rien n'est facturé).

GET/api/verify?hash={sha256}publicVérifier si un hash est certifié

N'importe qui peut l'interroger, sans clé. Seules les certifications confirmées dans la chaîne sont renvoyées.

Requête
curl "https://proovik.com/api/verify?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Réponse
{
  "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}publicTélécharger le certificat PDF

La réponse de /api/certify inclut certificate_url : un lien signé (paramètre t) qui affiche aussi tes métadonnées privées. Sans t, le même endpoint sert à tout le monde la version publique du certificat. Le PDF contient en pièce jointe le paquet de preuve PVK-PROOF/1, vérifiable sans Proovik.

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

Erreurs: 404 not_found · 409 certification_pending (JSON, pas de PDF : il n'y a pas encore de certificat) · 429 rate_limited (60 téléchargements par heure et par IP).

GET/api/certify/proof?hash={sha256}cléPreuve Merkle d'une certification

Renvoie le chemin Merkle et la racine ancrée d'une certification réalisée avec ta clé. Celles d'autres comptes répondent 404.

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

Traçabilité des lots

Lots et événements chaînés par hash et ancrés par lots Merkle

Chaque événement pointe vers le hash du précédent ; le premier pointe vers le hash du lot. Les enregistrements sont ancrés dans la chaîne Kaspa par cycles de quelques minutes : l'état passe de pending à confirmed sans que tu aies à faire quoi que ce soit. Identifiants GS1 (GTIN, SGTIN, GLN) validés par chiffre de contrôle.

POST/api/trace/batchcléCréer un lot

Obligatoire : product_name. Facultatifs : batch_id (généré à défaut), gtin, sgtin (unique dans tout le système ; un doublon répond 409), origin, origin_gln, origin_lat/origin_lng, quantity, quantity_unit, metadata. Accepte l'en-tête Idempotency-Key.

Requête
curl -X POST https://proovik.com/api/trace/batch \
  -H "Authorization: Bearer VOTRE_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 }
  }'
Réponse · 201
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "payload_hash": "7f83b165…6d9069",
  "created_at": "2026-09-05T10:00:00+00:00"
}
POST/api/trace/eventcléAjouter un événement

Obligatoires : batch_id et event_type, l'un de COMMISSION, OBSERVE, TRANSFORM, SHIP, RECEIVE, AGGREGATE, DISAGGREGATE, CUSTOM. Facultatifs : location {name, gln, lat, lng}, actor {name, id, role}, data, evidence_hash, gs1_bizstep.

Requête
curl -X POST https://proovik.com/api/trace/event \
  -H "Authorization: Bearer VOTRE_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 }
  }'
Réponse · 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}clé facultativeLire un lot avec ses événements

Sans clé, tu obtiens la vue publique du lot ; avec ta clé, les données complètes de tes propres lots.

Requête
curl "https://proovik.com/api/trace/batch/BATCH-20260905-A1B2C3D4" \
  -H "Authorization: Bearer VOTRE_API_KEY"
GET/api/trace/verify/{batch_id}clé facultativeVérifier l'intégrité d'un lot

Recalcule le hash du lot, la chaîne d'événements et les preuves Merkle face à ce qui est ancré. overall_valid n'est true que si tout concorde ; fully_verified exige en plus que tous les événements soient confirmés.

Requête
curl "https://proovik.com/api/trace/verify/BATCH-20260905-A1B2C3D4"
Réponse
{
  "success": true,
  "batch_id": "BATCH-20260905-A1B2C3D4",
  "verification": {
    "overall_valid": true,
    "batch_integrity": { "valid": true, … },
    "chain_integrity": { "valid": true, … },
    "fully_verified": true
  }
}

Existent aussi, avec clé : 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 et GET /api/trace/batch/{batch_id}/qr. Détails dans la référence complète.

Limites par clé : 60 écritures et 300 lectures par minute. Au-delà, la réponse est 429 avec Retry-After.

Vérification indépendante (PVK-PROOF/1)

Contrôler une preuve sans faire confiance à Proovik

Le vérificateur recalcule les quatre maillons de la preuve : le hash du document est dans la transaction, la transaction est dans l'arbre Merkle du bloc, l'en-tête reproduit le hash du bloc et cet en-tête porte une preuve de travail valide. Le hash du document, c'est toujours toi qui le fournis : il n'est jamais lu dans le paquet. Trois verdicts : VALIDO, INCOMPLETO (impossible à déterminer ; ne compte jamais comme valide) et INVALIDO.

POST/api/verify/proofpublicVérifier un paquet de preuve

Envoie le fichier .pvkproof.json (celui joint au PDF) ou le paquet en JSON, avec le SHA-256 de ta copie du document. Aucune consultation du réseau : il vérifie ce que tu lui donnes. Sans clé.

Requête
curl -X POST https://proovik.com/api/verify/proof \
  -F "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -F "[email protected]"
Réponse
{
  "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}publicReconstruire et vérifier depuis la chaîne

Avec le seul txid et le hash, il reconstruit le paquet en interrogeant le réseau Kaspa. L'en-tête complet du bloc n'est disponible qu'environ 40 heures : passé ce délai, les maillons 3 et 4 restent INCOMPLETO. Sans clé ; CORS ouvert ; 30 requêtes par heure et par IP.

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

Spécification et vérificateur en ligne

Ce que cette API n'a pas (encore)

  • Webhooks sortants. Rien ne te prévient quand une transaction se confirme. Pour les certifications, renvoie le même hash à POST /api/certify ou interroge GET /api/verify?hash= ; pour la traçabilité, interroge GET /api/trace/verify/{batch_id}.
  • SDK. Il n'existe aucune bibliothèque officielle, dans aucun langage. C'est du HTTP et du JSON : n'importe quel client HTTP suffit.
  • Fichier OpenAPI. La référence des champs et des réponses se trouve dans la documentation technique liée ci-dessous.
  • Clés en libre-service, clés multiples ou scopes. Une clé par compte, activée à la main.
  • Environnement de test. Chaque certification réelle consomme un crédit. Pour essayer sans dépenser, utilise les endpoints publics de consultation et de vérification.
PVK-PROOF/1

Référence complète et vérificateur

La documentation technique décrit tous les champs et toutes les réponses (pour l'instant en espagnol uniquement). Le vérificateur en ligne contrôle n'importe quel certificat sans compte.

Documentation technique Vérificateur en ligne Demander une clé d'API