Lumiere LUMIERE
Créer un compte
Guide d'intégration

Certifier et vérifier des documents par API

L'API Lumiere permet à votre système (scolarité, RH, plateforme d'inscription…) d'ancrer l'empreinte d'un document sur la blockchain Lumiere au moment où il est délivré, puis à n'importe qui de vérifier son authenticité par la suite. Une intégration tient en deux appels : signer, puis vérifier.

URL de basehttps://lumiere.bj/api/v1
Formatmultipart/form-data en entrée, application/json en sortie
Authentificationen-tête X-Api-Key
Exemples de code

Authentification

Chaque requête doit porter une clé API valide dans l'en-tête X-Api-Key. Il n'y a ni OAuth ni jeton à renouveler : la clé est un secret statique, à traiter comme un mot de passe.

key

La clé n'est affichée qu'une seule fois, à sa création. Si vous la perdez, révoquez-la et générez-en une nouvelle.

X-Api-Key: votre_cle_secrete

Démarrage rapide

# 1. Certifier le diplôme au moment de sa délivrance
curl -X POST https://lumiere.bj/api/v1/documents/sign \
  -H "X-Api-Key: votre_cle_secrete" \
  -F "file=@diplome_koffi_2026.pdf" \
  -F "delivre_a=Koffi Adjovi" \
  -F "type_document=Diplôme de Licence"

# 2. Plus tard, vérifiez avec le hash reçu
curl https://lumiere.bj/api/v1/documents/verify/2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f \
  -H "X-Api-Key: votre_cle_secrete"

Exemples complets à exécuter

Un script autonome par langage — copiez-le tel quel dans un fichier, remplacez la clé API et le chemin du document, et lancez-le. Chacun certifie un fichier puis vérifie immédiatement son empreinte.

certifier.sh — bash certifier.sh fichier.pdf "Nom du bénéficiaire"
#!/bin/bash
API_KEY="votre_cle_secrete"
FICHIER="$1"
BENEFICIAIRE="$2"

REPONSE=$(curl -s -X POST https://lumiere.bj/api/v1/documents/sign \
  -H "X-Api-Key: $API_KEY" \
  -F "file=@$FICHIER" \
  -F "delivre_a=$BENEFICIAIRE")

echo "Certifié : $REPONSE"

HASH=$(echo "$REPONSE" | grep -o '"hash":"[a-f0-9]*"' | cut -d'"' -f4)

echo "Vérification :"
curl -s https://lumiere.bj/api/v1/documents/verify/$HASH -H "X-Api-Key: $API_KEY"
POST /documents/sign

Ancre un document sur la blockchain Lumiere. Envoyez le fichier tel quel — Lumiere calcule lui-même l'empreinte SHA-256. L'appel est idempotent : renvoyer un fichier déjà certifié renvoie la certification existante (200) plutôt que d'en créer une seconde.

ChampDescription
filerequisLe document original. 10 Mo max.
delivre_arequisNom du bénéficiaire.
nom_documentoptionnelPar défaut, le nom du fichier envoyé.
type_documentoptionnelEx : « Diplôme », « Relevé de notes ».
verifie_paroptionnelEntité certificatrice. Par défaut, le nom associé à votre clé.
date_delivranceoptionnelSi différente d'aujourd'hui.
remplace_hashoptionnelVoir Remplacer un document.
motif_remplacementrequis avec remplace_hash5 caractères min.
{
  "success": true,
  "hash": "2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f",
  "blockchain_status": "confirmed",
  "document": { "…" },
  "remplace": null,
  "conseil": "Conservez cette empreinte pour un futur remplacement."
}
GET /documents/verify/{hash}

Vérifie un document à partir de son empreinte SHA-256 (64 caractères hexadécimaux). Lumiere consulte son registre et la blockchain, et renvoie le résultat de la vérification.

curl https://lumiere.bj/api/v1/documents/verify/2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f \
  -H "X-Api-Key: votre_cle_secrete"

Réponse (identique pour la vérification par fichier) :

{
  "success": true,
  "hash": "2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f",
  "verified": true,
  "result": "authentique",
  "document": { "…" },
  "superseded": false,
  "current_version": null,
  "revoked": false,
  "revoked_at": null,
  "revocation_reason": null
}

Valeurs de result :

resultverifiedHTTPSignification
authentiquetrue200Document certifié et toujours valable.
remplacetrue200Authentique, mais une version plus récente a été certifiée : voir current_version.
revoquefalse200Certifié puis révoqué : ne doit plus être accepté. Voir revoked_at et revocation_reason.
inconnufalse404Aucun document certifié ne correspond à cette empreinte : le fichier n'a pas été certifié par Lumiere, ou il a été modifié.
POST /documents/verify

Vérification, à partir du fichier lui-même — champ file, requis, 10 Mo max.

curl -X POST https://lumiere.bj/api/v1/documents/verify \
  -H "X-Api-Key: votre_cle_secrete" \
  -F "file=@diplome_koffi_2026.pdf"
warning

Le hash est calculé sur le contenu binaire exact. Une simple réexportation du PDF peut changer l'empreinte et faire échouer la vérification d'un document pourtant authentique.

Remplacer un document

Un document certifié n'est jamais modifié ni supprimé. Pour corriger ou mettre à jour un document déjà émis, certifiez la nouvelle version normalement, en ajoutant le hash de l'ancienne dans remplace_hash et un motif dans motif_remplacement.

  1. Conservez le hash reçu à chaque certification (le champ conseil vous le rappelle).
  2. Le jour d'une correction, certifiez le nouveau fichier avec remplace_hash + motif_remplacement (obligatoire, 5 caractères min.).
  3. Lumiere vérifie que vous êtes bien propriétaire du document référencé — impossible de remplacer le document de quelqu'un d'autre.
  4. L'ancienne version reste consultable, mais toute vérification affichera qu'elle a été remplacée, avec un lien vers la version actuelle.
link

Ce n'est jamais automatique : Lumiere ne rapproche pas deux documents entre eux tout seul, même s'ils semblent similaires — c'est à vous de le déclarer explicitement.

curl -X POST https://lumiere.bj/api/v1/documents/sign \
  -H "X-Api-Key: votre_cle_secrete" \
  -F "file=@diplome_koffi_2026_corrige.pdf" \
  -F "delivre_a=Koffi Adjovi" \
  -F "remplace_hash=2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f" \
  -F "motif_remplacement=Correction de l'orthographe du nom"

Révoquer un document

POST /documents/revoke

Révoquez un document qui ne doit plus être accepté (fraude constatée, acte annulé…) sans en certifier de nouvelle version. Pour une simple correction, préférez le remplacement.

ChampDescription
hashrequisEmpreinte SHA-256 du document, reçue lors de sa certification.
motifrequisRaison de la révocation, 5 à 500 caractères. Elle est affichée à toute personne qui vérifie le document.
  1. Vous ne pouvez révoquer que les documents que vous avez vous-même certifiés.
  2. La révocation est définitive : elle est inscrite sur la blockchain à la suite de l'ancrage d'origine, qui n'est ni modifié ni effacé.
  3. Dès la réponse, toute vérification du document renvoie "result": "revoque" et "verified": false, avec la date et le motif.
  4. Si la blockchain est momentanément indisponible, revocation_blockchain_status vaut failed : l'inscription est réessayée par Lumiere, sans action de votre part.
curl -X POST https://lumiere.bj/api/v1/documents/revoke \
  -H "X-Api-Key: votre_cle_secrete" \
  -F "hash=2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f" \
  -F "motif=Diplôme annulé par décision du conseil de discipline"

Réponse :

{
  "success": true,
  "hash": "2f7de70655779b5bedabdee7bf485be72c51f253bec56052c3be542a381259f",
  "revoked_at": "2026-11-06T09:12:44.000000Z",
  "revocation_reason": "Diplôme annulé par décision du conseil de discipline",
  "revocation_blockchain_status": "confirmed",
  "revocation_tx_id": "9c1f…",
  "message": "Document révoqué. La révocation est inscrite sur la blockchain."
}

Codes d'erreur

CodeSignification
401Clé API absente, invalide ou révoquée.
404Aucun document ne correspond à ce hash.
409Document déjà révoqué.
422Champ requis manquant/invalide, ou document à remplacer ou à révoquer introuvable / ne vous appartenant pas.
429Trop de requêtes — limitez la fréquence d'appel.

Bonnes pratiques

Besoin d'une clé API ?

Créez un compte certificateur, puis générez votre clé depuis votre espace client une fois validé.

Créer un compte