CapsulizeCapsulize

API Documentation

Documentation complète de l'API Capsulize pour l'horodatage blockchain de documents.

Vue d'ensemble

À propos de l'API

L'API Capsulize permet d'horodater des documents sur la blockchain Base (Ethereum Layer 2) de manière programmatique. Chaque document est transformé en empreinte cryptographique SHA-256 qui est enregistrée sur la blockchain pour créer une preuve d'antériorité inviolable. Nous ne stockons pas les documents sur nos serveurs, après avoir capturé l'empreinte SHA-256, le document est supprimé.

Horodatage instantané

Traitement en 30 secondes maximum

Preuve blockchain

Timestamp inviolable sur Base

Certificats PDF

Génération automatique

🚀 Inscription autonome

Créez votre compte, achetez vos crédits et obtenez vos identifiants API en quelques clics !

S'inscrire maintenant Acheter des crédits

Authentification

Méthode HMAC-SHA256

L'API utilise une authentification HMAC-SHA256 pour garantir la sécurité des requêtes. Cette méthode combine votre clé API publique et votre secret privé pour créer une signature unique.

🔑 Comment ça marche ?

  1. Vous recevez une API Key (publique) et un API Secret (privé)
  2. Pour chaque requête, vous calculez une signature avec votre secret
  3. Le serveur recalcule la même signature et compare
  4. Si les signatures correspondent, l'authentification réussit

Headers requis

X-API-Key: cap_1234567890abcdef
X-Signature: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
X-Timestamp: 1703123456789
📝 Calcul de la signature

String à signer :

METHOD + ENDPOINT + TIMESTAMP

Exemple :

POST/certificates/upload1703123456789

Note : ENDPOINT = chemin sans le domaine (ex: /certificates/upload)

🔒 Sécurité
  • • Chaque client a son propre secret unique
  • • Timestamp limite la validité temporelle
  • • Impossible de modifier la requête sans invalider la signature
  • • Protection contre les attaques de replay

Exemples par langage

🖥️ cURL
# Générer la signature (exemple avec bash)
API_KEY="cap_1234567890abcdef"
API_SECRET="a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
TIMESTAMP=$(date +%s)000
METHOD="POST"
ENDPOINT="/certificates/upload"
SIGNATURE=$(echo -n "$METHOD$ENDPOINT$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | xxd -p)
# ...
curl -X POST "https://api.capsulize.app/pro/certificates/upload" \
-H "X-API-Key: $API_KEY" \
-H "X-Signature: $SIGNATURE" \
-H "X-Timestamp: $TIMESTAMP" \
-F "file=@document.pdf"
🐍 Python
import hmac
import hashlib
import time
# ...
def create_signature(method, endpoint, timestamp, api_secret):
# endpoint = "/certificates/upload" (sans le domaine)
string_to_sign = method + endpoint + str(timestamp)
return hmac.new(
api_secret.encode('utf-8'),
string_to_sign.encode('utf-8'),
hashlib.sha256
).hexdigest()
🟨 JavaScript/Node.js
const crypto = require('crypto');
# ...
function createSignature(method, endpoint, timestamp, apiSecret) {
// endpoint = "/certificates/upload" (sans le domaine)
const stringToSign = method + endpoint + timestamp;
return crypto
.createHmac('sha256', apiSecret)
.update(stringToSign)
.digest('hex');
}
🐘 PHP
function createSignature($method, $endpoint, $timestamp, $apiSecret) {
// $endpoint = "/certificates/upload" (sans le domaine)
$stringToSign = $method . $endpoint . $timestamp;
return hash_hmac('sha256', $stringToSign, $apiSecret);
}

⚠️ Important

  • • Gardez votre API Secret privé - ne l'exposez jamais dans le code client
  • • Utilisez HTTPS pour toutes les requêtes
  • • Timestamp précis - synchronisez l'heure avec un serveur NTP
  • • Gestion d'erreur - implémentez des retry en cas d'échec d'authentification

Endpoints

Upload d'un document

POST
https://api.capsulize.app/pro/certificates/upload

Description

Horodate un document sur la blockchain. Le fichier est transformé en empreinte SHA-256 et enregistré sur Base (Ethereum Layer 2). Un certificat PDF est généré automatiquement.

⏱️ Traitement asynchrone

La publication blockchain peut prendre quelques secondes. L'API renvoie immédiatement un certificate_id et traite l'horodatage en arrière-plan. Utilisez le webhook pour être notifié automatiquement du résultat.

Paramètres

fileFichier à horodater (PDF, DOC, TXT, JPG, PNG, ZIP)
webhook_urlURL de webhook (optionnel) - Notification automatique quand l'horodatage est terminé

Réponse

{
"success": true,
"certificate_id": "cert_abc123def456",
"file_hash": "0x1234567890abcdef...",
"file_name": "document.pdf",
"file_size": 1024000,
"status": "pending",
"credits_used": 1,
"credits_remaining": 149
}
Note : Le statut "pending" indique que l'horodatage blockchain est en cours. Utilisez l'endpoint /status ou le webhook pour suivre l'avancement.

Consultation du statut

GET
https://api.capsulize.app/pro/certificates/{certificate_id}/status

Description

Récupère le statut de traitement d'un certificat et les métadonnées blockchain une fois l'horodatage terminé.

Paramètres

certificate_idID du certificat

Statuts possibles

pendingEn cours de traitement blockchain
completedHorodatage terminé avec succès
failedÉchec de l'horodatage blockchain
expiredDélai de traitement dépassé

Réponse

{
"success": true,
"certificate_id": "cert_abc123def456",
"status": "completed",
"file_hash": "0x1234567890abcdef...",
"file_name": "document.pdf",
"blockchain_tx_hash": "0xabcdef1234567890...",
"blockchain_timestamp": 1640995200,
"block_number": 12345678,
"explorer_url": "https://basescan.org/tx/0xabcdef...",
"certificate_url": "https://api.capsulize.app/pro/certificates/cert_abc123def456/download"
}

Téléchargement du certificat

GET
https://api.capsulize.app/pro/certificates/{certificate_id}/download

Description

Télécharge le certificat PDF généré pour un document horodaté. Le certificat contient toutes les informations blockchain et peut être utilisé comme preuve juridique.

Paramètres

certificate_idID du certificat

Réponse

Fichier PDF du certificat avec les en-têtes :

Content-Type: application/pdf
Content-Disposition: attachment; filename="certificat.pdf"

Consultation du solde de crédits

GET
https://api.capsulize.app/pro/credits/balance

Description

Consulte votre solde de crédits restants et les statistiques d'utilisation de l'API.

Réponse

{
"success": true,
"credits_balance": 150,
"credits_used": 50,
"credits_purchased": 200
}

Codes d'erreur

CodeDescriptionSolution
400Requête invalideVérifier le format des données et les paramètres
401Authentification échouéeVérifier les clés API et la signature
402Crédits insuffisantsAcheter des crédits supplémentaires
403Accès interditVérifier les permissions de votre compte
404Ressource non trouvéeVérifier l'ID du certificat
429Trop de requêtesRespecter les limites de débit (1000/h)
500Erreur serveurContacter le support technique

Tarifs et crédits

Système de crédits

L'API utilise un système de crédits prépayés. Chaque horodatage de document consomme 1 crédit, quel que soit la taille du fichier.

1 crédit = 1 horodatage

Chaque document horodaté consomme exactement 1 crédit

Pas de limite

Aucune limite sur le nombre de fichiers par jour

Tarifs

À partir de 5 € HT
  • • 5€ = 20 crédits (0,25€/doc)
  • • 10€ = 50 crédits (0,20€/doc)
  • • 15€ = 100 crédits (0,15€/doc)
  • • 30€ = 300 crédits (0,10€/doc)

Prêt à intégrer l'API ?

Inscrivez-vous maintenant pour obtenir vos credentials API et commencer à horodater vos documents.

S'inscrire à l'API Acheter des crédits Support technique