Collecter des pièces KYC

Cette recette montre comment collecter les pièces justificatives KYC d'un client (carte d'identité, justificatif de domicile, RIB, Kbis) sans jamais exposer ces documents en clair sur vos serveurs ni manipuler de fichiers depuis votre back-office. Vous créez un intake (réception sécurisée) configuré avec une référence obligatoire, vous laissez le client déposer ses pièces depuis le navigateur, vous rattachez chaque dépôt à un dossier grâce à une référence opaque, puis vous réagissez à l'évènement request.submitted pour récupérer les métadonnées et traiter le dossier. Les pièces sont conservées en Union européenne et le mode de bout en bout garde la clé chez vous : Coffrify relaie sans lire.

Le modèle en bref

Un intake expose deux clés. La clé publiable (cip_) est sûre côté navigateur et restreinte par origine : c'est elle qui sert à déposer les pièces depuis la page de votre client. La clé secrète est votre clé d'API cof_ portant le scope intake:read ou intake:write : elle reste sur votre serveur et sert à lister et récupérer les dépôts. La référence opaque (client_reference) est la pièce maîtresse de cette recette : c'est une chaîne que vous choisissez (par exemple un identifiant de dossier KYC interne) qui répond à la question « donne-moi toutes les pièces du dossier X » sans que Coffrify n'apprenne jamais l'identité réelle derrière ce dossier.

1. Créer l'intake KYC

Créez l'intake depuis votre serveur avec votre clé cof_. Activez reference_required pour qu'aucun dépôt ne soit accepté sans référence de dossier, et listez les origines autorisées (allowed_origins) à partir desquelles le formulaire de dépôt pourra s'exécuter. La réponse renvoie la clé publiable une seule fois : conservez-la pour configurer le dépôt navigateur.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const intake = await coffrify.intakes.create({
  name: 'Vérification KYC clients',
  allowed_origins: ['https://app.exemple.fr'],
  reference_required: true,
  metadata_policy: 'envelope',
});
 
console.log(intake.id);              // in_...
console.log(intake.publishable_key); // cip_live_... (à ne plus jamais réafficher)

L'objet renvoyé contient id, slug, reference_required, allowed_origins, le bloc e2e (état du mode de bout en bout) et le bloc limits. La publishable_key n'apparaît que dans cette réponse de création : si vous la perdez, faites tourner une nouvelle clé plutôt que de chercher à la relire.

2. Rattacher chaque dépôt à un dossier

Côté navigateur, votre client dépose ses pièces avec le SDK de dépôt et la clé publiable. C'est à ce moment que vous fixez la référence opaque du dossier : passez votre identifiant interne en client_reference. Vous pouvez aussi joindre quelques métadonnées d'enveloppe non sensibles (par exemple le type de document attendu) pour vous aider à trier à la réception.

• Générez côté serveur un identifiant de dossier opaque (par exemple kyc_8f3a2b) et transmettez-le à la page de dépôt du client.
• Le client choisit ses fichiers ; le dépôt est chiffré dans son navigateur quand l'intake est en mode de bout en bout, puis téléversé.
• Chaque dépôt portant la même référence est ainsi regroupé sous le même dossier côté serveur, sans identité réelle.

3. Réagir à request.submitted

Pour être averti dès qu'un client a terminé son dépôt, abonnez un webhook à l'évènement request.submitted. Vous recevrez une notification serveur à serveur que vous traitez de façon asynchrone, plutôt que d'interroger l'API en boucle. Créez le webhook avec votre clé cof_ (scope webhooks:manage).

curl -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer $COFFRIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.exemple.fr/webhooks/coffrify",
    "events": ["request.submitted", "request.completed"]
  }'

À la réception d'un évènement request.submitted, vérifiez la signature, puis utilisez la référence du dossier pour récupérer la liste des pièces déjà reçues. Filtrez l'appel de liste par reference afin d'obtenir uniquement les dépôts du dossier concerné. Chaque entrée est un objet intake_document qui ne contient que des métadonnées (client_reference, metadata, status, files_count, total_size_bytes, encrypted), jamais le contenu en clair.

// Dans votre gestionnaire de webhook, après vérification de la signature
const reference = event.data.client_reference; // ex. kyc_8f3a2b
 
const docs = await coffrify.intakes.documents.list(intakeId, {
  reference,
  status: 'received',
  limit: 100,
});
 
for (const doc of docs.data) {
  console.log(doc.id, doc.files_count, doc.metadata.document_type);
}

La signature du webhook voyage dans les en-têtes webhook-id, webhook-timestamp et webhook-signature (format v1,<base64>). Dédupliquez toujours sur webhook-id : le même identifiant est réutilisé à chaque nouvelle tentative et à chaque rejeu, ce qui rend votre traitement idempotent même si l'évènement vous parvient plusieurs fois.

4. Récupérer une pièce pour vérification

Pour examiner une pièce précise, récupérez le document par son identifiant. La réponse renvoie la liste files, où chaque fichier porte une URL download_url valable 300 secondes, ainsi qu'un bloc encryption lorsque l'intake est en mode de bout en bout. Dans ce mode, le blob téléchargé est chiffré : c'est vous, détenteur de la clé, qui le déchiffrez de votre côté. Coffrify ne voit jamais le contenu.

5. Gérer la rétention

Le KYC impose une conservation limitée dans le temps. Une fois un dossier vérifié et la décision archivée de votre côté, supprimez les pièces correspondantes pour respecter la minimisation des données. Vous pouvez supprimer l'intake entier quand une campagne de vérification est terminée, ou plus finement piloter la suppression dossier par dossier depuis votre logique métier. Pour les obligations probatoires globales, exposez vos données de rétention via les points de terminaison RGPD.

Avec ce schéma, vous obtenez une collecte KYC conforme et minimaliste : votre serveur ne manipule que des références opaques et des métadonnées, les pièces restent chiffrées et en Union européenne, et la rétention se pilote par dossier. Pour aller plus loin, ajoutez les évènements request.created et request.expired à votre webhook afin de relancer automatiquement les clients qui n'ont pas terminé leur dépôt dans le délai imparti.