Intégration headless avec @coffrify/sdk

L'intégration headless avec <code>@coffrify/sdk</code> vous donne le contrôle total du flux de réception. Vous créez et gérez les points de dépôt depuis votre back-end Node, vous embarquez le module navigateur dans votre propre interface, et vous récupérez les dépôts via l'API REST. Le chiffrement de bout en bout reste actif : Coffrify ne lit jamais le contenu des fichiers, seule votre clé privée le peut. Ce guide vous accompagne de l'installation du SDK serveur jusqu'à la récupération des dépôts, en passant par l'upload côté navigateur avec barre de progression.

Prérequis

Vous avez besoin d'un compte Coffrify avec une clé API serveur (préfixe <code>cof_live_</code>, <code>cof_test_</code> ou <code>cof_sandbox_</code>) disposant du scope <code>intake_write</code>. Côté navigateur, vous utiliserez la <b>publishable_key</b> (préfixe <code>cip_</code>) renvoyée à la création de l'intake, affichée une seule fois. Le SDK Node nécessite Node 18 ou supérieur. Aucun pré-requis particulier côté navigateur, le module est livré en ESM et fonctionne avec n'importe quel bundler.

1. Installer le SDK côté Node

Le paquet <code>@coffrify/sdk</code> expose un client typé pour toutes les ressources publiques (intakes, dépôts, fichiers). Installez-le avec votre gestionnaire de paquets habituel, puis stockez votre clé API dans une variable d'environnement, jamais en clair dans le code.

npm install @coffrify/sdk

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({
  apiKey: process.env.COFFRIFY_API_KEY,
});

2. Créer un intake

Un intake correspond à un point de dépôt unique, par exemple « Pièces dossier client » pour un cabinet d'avocats. Vous précisez son nom, les origines autorisées (CORS) si vous l'embarquez sur un site, la politique sur les métadonnées et si une référence de dossier est obligatoire. Pensez à fournir un <code>Idempotency-Key</code> si vous créez plusieurs intakes en lot afin d'éviter les doublons en cas de re-essai réseau.

const intake = await coffrify.intakes.create({
  name: 'Pièces dossier client',
  slug: 'pieces-dossier',
  allowed_origins: ['https://cabinet-dupont.fr'],
  metadata_policy: 'allow',
  reference_required: true,
}, {
  idempotencyKey: 'intake-pieces-dossier-2026-06',
});
 
console.log('Intake ID    :', intake.id);
console.log('Publishable  :', intake.publishable_key);

3. Initialiser le module navigateur

Côté front, vous chargez le module Coffrify Intake depuis le CDN officiel, puis vous instanciez la classe <code>Coffrify.Intake</code> avec la clé publique récupérée à l'étape précédente. Cette instance gère le chiffrement de bout en bout en local : la phrase secrète et les codes de récupération sont générés dans le navigateur et ne quittent jamais l'appareil de l'utilisateur.

<script src="https://app.coffrify.com/sdk/coffrify-intake.js"></script>
<script>
  const intake = new Coffrify.Intake({
    publishableKey: 'cip_live_VOTRE_CLE_PUBLIQUE',
  });
</script>

4. Uploader des fichiers avec progression

La méthode <code>intake.upload(files, options)</code> prend un <code>FileList</code> ou un tableau de <code>File</code>, chiffre chaque fichier en local, puis téléverse les blobs chiffrés vers Coffrify. Les options vous permettent d'attacher une référence de dossier, des métadonnées (acceptées seulement si <code>metadata_policy</code> vaut <code>allow</code>), et des callbacks pour suivre la progression et gérer les erreurs.

const fileInput = document.querySelector('#files');
const progressBar = document.querySelector('#progress');
 
fileInput.addEventListener('change', async (event) => {
  try {
    const result = await intake.upload(event.target.files, {
      reference: 'DOSSIER-2026-0481',
      metadata: {
        type_piece: 'acte de vente',
        urgence: 'normale',
      },
      onProgress: ({ loaded, total, percent }) => {
        progressBar.value = percent;
        console.log(`${loaded} / ${total} octets`);
      },
      onComplete: (deposit) => {
        console.log('Dépôt reçu :', deposit.id);
      },
      onError: (error) => {
        console.error('Échec :', error.code, error.message);
      },
    });
  } catch (error) {
    console.error(error);
  }
});

5. Récupérer les dépôts côté serveur

Depuis votre back-end, vous listez les dépôts reçus sur un intake avec <code>coffrify.intakes.documents.list</code>. Vous pouvez filtrer par référence de dossier pour retrouver tous les envois liés à un client. La pagination utilise un curseur opaque : tant que <code>has_more</code> vaut <code>true</code>, vous repassez <code>next_cursor</code> à l'appel suivant.

async function listAllDeposits(intakeId: string, reference: string) {
  const deposits = [];
  let cursor: string | undefined;
 
  do {
    const page = await coffrify.intakes.documents.list(intakeId, {
      reference,
      limit: 100,
      cursor,
    });
 
    deposits.push(...page.data);
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
 
  return deposits;
}
 
const dossier = await listAllDeposits(intake.id, 'DOSSIER-2026-0481');
console.log(`${dossier.length} dépôt(s) reçus.`);

6. Télécharger un dépôt chiffré

L'appel détail renvoie pour chaque fichier une URL pré-signée (<code>download_url</code>, valable 300 secondes via <code>download_expires_in</code>) ainsi que l'enveloppe technique nécessaire au déchiffrement local. Le déchiffrement se fait dans le navigateur ou dans un client de confiance, jamais sur les serveurs Coffrify.

const deposit = await coffrify.intakes.documents.retrieve(
  intake.id,
  'dep_01HZX9K8VQRJ7M2NPCDEFGH4',
);
 
for (const file of deposit.files) {
  console.log(file.name, file.download_url);
  // Le déchiffrement a lieu côté client avec la phrase secrète du compte.
}

Prochaines étapes

Vous disposez désormais d'un flux complet : création d'intakes depuis votre serveur, upload chiffré depuis votre interface, récupération filtrée par référence de dossier. Pour aller plus loin, configurez plusieurs intakes par typologie de dossier, restreignez <code>allowed_origins</code> à vos domaines de production, et exploitez la pagination par curseur pour exporter vos dépôts dans votre propre archivage.