Intégration API

L'API REST de Chaindoc vous permet d'automatiser vos flux documentaires, collecter des signatures et synchroniser les événements en temps réel. Voici comment démarrer, les concepts essentiels et les patterns les plus utilisés.

Ce que vous pouvez faire avec l'API

L'API vous donne un accès programmatique à tout ce que fait Chaindoc : uploader des documents, créer des demandes de signature, gérer des équipes et écouter les événements via des webhooks. C'est exactement la même API qui fait tourner l'application web.

Trois façons d'intégrer

Choisissez celle qui correspond à votre stack. En pratique, la plupart des apps en production utilisent le Server SDK côté backend et l'Embed SDK côté frontend.

• REST API — requêtes HTTP directes, fonctionne avec n'importe quel langage. Flexibilité maximale.
• Server SDK — wrapper Node.js avec typage TypeScript, retries automatiques et gestion d'erreurs (`@chaindoc_io/server-sdk`)
• Embed SDK — intègre une interface de signature dans votre app, vos utilisateurs ne quittent jamais votre site (`@chaindoc_io/embed-sdk`)

Si vous n'avez pas encore installé les SDKs, le guide d'installation couvre la configuration npm pour React, Vue, Angular et Next.js.

Exemple rapide

Voici le même appel << créer un document >> en trois variantes. Honnêtement, la version SDK est la plus concise, mais l'appel REST brut montre exactement ce qui passe sur le réseau.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Authentification

Chaque requête a besoin d'une clé API dans le header Authorization :

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Il existe deux types de clés, et les confondre est l'erreur d'intégration la plus courante :

• Clés publiques (`pk_`) — lecture seule, sûres pour le code frontend
• Clés secrètes (`sk_`) — lecture/écriture complète, backend uniquement. Ne les exposez jamais côté client.
• Les deux existent en test (`_test_`) et live (`_live_`). Les clés test utilisent le bac à sable.

Rate limits

L'API renvoie les infos de rate limit dans les headers de réponse. Si vous atteignez la limite, vous recevez une réponse 429. Attendez et réessayez.

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

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

Le Server SDK gère les retries automatiquement avec backoff exponentiel. Si vous utilisez HTTP brut, implémentez cette logique vous-même.

Gestion des erreurs

Les erreurs reviennent au format JSON avec un code status, un message et (pour les erreurs de validation) une liste de problèmes spécifiques :

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

Codes status courants : 400 (mauvaise requête), 401 (clé invalide), 403 (plan sans API), 404 (non trouvé), 429 (rate limité), 500 (erreur serveur). Pour les erreurs 5xx, réessayez avec backoff.

Patterns d'intégration courants

Flux de signature complet (embed)

Voici le truc : le pattern le plus utilisé consiste à uploader un document, l'envoyer pour signatures et afficher l'UI de signature dans votre app.

Le guide de démarrage rapide contient le code complet pour ce flux.

Signature par email (sans embed)

Si vos signataires n'utilisent pas votre app, mettez `embeddedFlow: false`. Chaindoc leur envoie un email avec un lien de signature. Vous recevez toujours les notifications webhook quand ils signent.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Les signataires reçoivent des liens par email
  message: 'Please review and sign this document',
});

Traitement de documents en masse

Pour les imports par lots, bouclez sur vos fichiers et uploadez-les un par un. Attention aux rate limits quand même. Si vous traitez des centaines de documents, ajoutez un petit délai entre les requêtes ou utilisez la logique de retry intégrée au SDK.

const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Intégration KYC

Pour les workflows haute sécurité, exigez une vérification d'identité avant signature. Chaindoc s'intègre avec Sumsub pour le KYC. Mettez `isKycRequired: true` sur la demande de signature, et les signataires passeront par la vérification d'identité avant de pouvoir signer.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optionnel : pré-vérifié
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Contrôle d'accès via API

Vous pouvez définir les permissions des documents par programmation. Restreignez l'accès à des emails spécifiques ou des rôles d'équipe :

await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Bonnes pratiques

• Gardez les clés API dans des variables d'environnement. Ne les commitez jamais dans le version control.
• Utilisez les clés test (`sk_test_`) pour le développement. Les clés live (`sk_live_`) tapent la production.
• Implémentez un backoff exponentiel pour les réponses 429. Le SDK le fait automatiquement.
• Vérifiez les signatures des webhooks avec HMAC pour prévenir les attaques par replay.
• Uploadez les fichiers avant de créer les documents. L'API a besoin du media ID de l'étape d'upload.
• Utilisez la pagination pour les endpoints qui retournent des listes. Ne tout récupérez pas d'un coup.
• Consultez le guide de sécurité avant de passer en production.

Exemples d'utilisation

Quelques patterns concrets que les équipes construisent avec l'API :

• E-commerce — générez automatiquement des contrats d'achat pour les commandes à valeur élevée et envoyez-les à la signature au checkout
• Onboarding RH — créez des contrats de travail à partir de templates et envoyez-les aux nouvelles recrues le jour de leur arrivée
• Intégration CRM — déclenchez des demandes de signature depuis les deals Salesforce ou HubSpot
• Archivage documentaire — ajoutez une vérification blockchain aux documents de votre système de stockage existant

Ce qu'il faut retenir

• Documentation API — référence complète des endpoints avec exemples requête/réponse
• SDKs — Server SDK et Embed SDK avec guides par framework
• Webhooks — configurez les notifications d'événements en temps réel
• Démarrage rapide — faites tourner votre première intégration en 10 minutes
• Installation — configuration npm pour tous les frameworks supportés