Documentation API REST Chaindoc

Référence complète des endpoints de l'API REST Chaindoc. Voici tout ce qu'il faut savoir : authentification, documents, signatures, upload média, sessions intégrées et vérification blockchain.

Vue d'ensemble

L'API vous donne un accès programmatique à tout ce que contient Chaindoc : les documents, les signatures, la vérification blockchain et la gestion d'équipe. C'est conçu pour un usage serveur-à-serveur et prend en charge les clés API publiques et secrètes.

• Documents — créez, modifiez et vérifiez des documents sur la blockchain
• Signatures — envoyez des demandes de signature et suivez leur avancement
• Média — uploadez des PDF, images et vidéos (max 10 par requête)
• Sessions intégrées — créez des sessions de signature pour votre frontend (utilise l'Embed SDK)
• KYC — partagez et vérifiez des données d'identité via l'intégration Sumsub

Authentification

Chaque requête nécessite une clé API dans l'en-tête Authorization. Il existe deux types :

Types de clés

• Clé publique (`pk_`) — lecture seule, sécurisée pour le code frontend
• Clé secrète (`sk_`) — lecture/écriture complète, backend uniquement. Ne jamais exposer dans le code client.

Obtenir vos clés

Utiliser les clés API

Incluez votre clé API dans l'en-tête Authorization avec l'authentification Bearer :

curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Limitation de débit

Les endpoints API sont soumis à des limites pour éviter les abus. Les plafonds varient selon le type d'endpoint.

• Endpoints généraux : 3 requêtes par 10 secondes
• Upload média : 3 requêtes par 10 secondes
• Vérification OTP : 5 requêtes par 60 secondes
• Opérations de lecture : 10 requêtes par 60 secondes
• Création de signatures : 20 requêtes par 3 secondes

Quand la limite est dépassée, vous recevrez une réponse 429 Too Many Requests. Les en-têtes de limitation sont inclus dans les réponses :

X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Gestion des erreurs

Codes HTTP

• 200 - Succès
• 201 - Ressource créée avec succès
• 400 - Requête invalide (erreur de validation)
• 401 - Non autorisé (clé API invalide ou manquante)
• 403 - Interdit (permissions insuffisantes)
• 404 - Ressource introuvable
• 429 - Trop de requêtes (limite dépassée)
• 500 - Erreur interne du serveur

Format des réponses d'erreur

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

API générale

Infos sur la clé API

Récupérez les informations concernant la clé API actuelle.

GET /me

Authorization: Bearer sk_live_xxxxx

Vérification de santé

Vérifiez la connectivité API et la validité de la clé.

GET /health

Authorization: Bearer sk_live_xxxxx

API Documents

Créer un document

Créez un nouveau document avec vérification blockchain. Quand le statut est 'published', le document est automatiquement vérifié sur la blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Modifier un document

Modifiez un document en créant une nouvelle version. Les versions précédentes sont conservées pour l'audit.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Modifier les droits d'accès

Modifiez les paramètres de contrôle d'accès d'un document.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Vérifier un document

Vérifiez l'authenticité d'un document via la blockchain. Retourne le statut de vérification avec le hash de transaction et l'ID de chaîne.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Statut de vérification

Récupérez le statut de vérification blockchain d'une version de document.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API Signatures

Créer une demande de signature

Créez une demande de signature pour un ou plusieurs destinataires. Activez le flux intégré pour l'intégration frontend.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Statut d'une demande

Vérifiez l'état d'une demande de signature et voyez quels signataires ont terminé.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Signer un document

Signez un document (si le propriétaire de la clé API est signataire).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Récupérer ses signatures

Récupérez toutes les signatures de l'utilisateur authentifié.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Liste des demandes

Récupérez toutes les demandes de signature avec support de la pagination.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API Upload média

Uploadez des fichiers pour les utiliser lors de la création de documents. Supporte PDF, images et vidéos. Maximum 10 fichiers par requête.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

API KYC

Partager des données KYC

Partagez des données KYC (Know Your Customer) avec des destinataires pour la vérification d'identité.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API Sessions intégrées

Créez des sessions intégrées pour la signature de documents dans votre application frontend. Les sessions sont valides 10 minutes.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Et maintenant ?

• Intégration API — patterns courants, bonnes pratiques et exemples complets
• SDKs — Server SDK et Embed SDK avec guides spécifiques par framework
• Webhooks — configurez des notifications d'événements en temps réel
• Installation — setup npm pour tous les frameworks supportés
• Sécurité — gestion des clés API et conformité