Gérer les dépôts reçus

Une fois votre Réception en place, vos déposants envoient des documents depuis le navigateur à l'aide de la clé publishable (cip_…). Tout le reste, lister les dépôts, suivre leur statut, récupérer leur contenu et les rattacher à vos dossiers internes, se passe côté serveur, avec votre clé secrète cof_… portant le scope intake:read. Cette clé ne doit jamais quitter votre back-office. Ce guide montre comment exploiter les dépôts reçus de bout en bout : pagination, filtrage, statuts, téléchargement du contenu, référence opaque, webhooks de la famille request.* et bonnes pratiques de rétention et de RGPD.

Lister les dépôts d'une Réception

Chaque Réception possède sa propre liste de dépôts. Vous la parcourez avec un appel authentifié par votre clé secrète. La réponse ne contient que des métadonnées : le contenu des fichiers, lui, se récupère dépôt par dépôt (voir plus bas).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_SECRET_KEY });
 
const page = await coffrify.intakes.documents.list('itk_123', {
  limit: 25,
});
 
for (const doc of page.data) {
  console.log(doc.id, doc.status, doc.client_reference);
}
 
console.log('Encore des dépôts ?', page.has_more);

La réponse est une liste paginée. Le champ data contient les dépôts, du plus récent au plus ancien. next_cursor et has_more vous permettent de récupérer la suite : rappelez le même point d'accès en passant cursor=<next_cursor> jusqu'à ce que has_more vaille false.

{
  "object": "list",
  "data": [
    {
      "object": "intake_document",
      "id": "doc_8f2a",
      "intake_id": "itk_123",
      "client_reference": "dossier-2026-0412",
      "metadata": { "type": "contrat", "lot": "A" },
      "status": "received",
      "files_count": 2,
      "total_size_bytes": 184320,
      "encrypted": true,
      "source": "sdk",
      "created_at": "2026-06-10T09:14:22Z"
    }
  ],
  "next_cursor": "eyJ0cyI6Ij...",
  "has_more": true,
  "limit": 25
}

Suivre les statuts

Un dépôt arrive avec le statut received. Après réception, Coffrify procède à une vérification automatique du dépôt ; si celle-ci échoue, le dépôt passe en rejected et son contenu n'est pas conservé. Pour ne traiter que les dépôts exploitables, filtrez sur le statut avec le paramètre status.

// Uniquement les dépôts valides et complets
const valides = await coffrify.intakes.documents.list('itk_123', {
  status: 'received',
  limit: 50,
});

Rattacher à un dossier interne avec la référence opaque

La référence opaque (client_reference) est l'outil qui vous permet de répondre à la question « donne-moi tout ce qui a été déposé pour le dossier X » sans que Coffrify ne connaisse jamais l'identité réelle derrière ce dossier. Vous l'attribuez au moment du dépôt, côté votre application, puis vous filtrez dessus avec le paramètre reference.

// Tous les dépôts rattachés à un dossier interne
const dossier = await coffrify.intakes.documents.list('itk_123', {
  reference: 'dossier-2026-0412',
});
 
console.log(`${dossier.data.length} dépôt(s) pour ce dossier`);

Récupérer le contenu d'un dépôt

Pour obtenir les fichiers d'un dépôt précis, appelez le point d'accès dédié. La réponse reprend les métadonnées du dépôt et ajoute la liste des fichiers, chacun avec une URL de téléchargement temporaire (download_url) valable quelques minutes (download_expires_in, en secondes). Téléchargez les fichiers sans tarder, puis traitez-les dans votre système.

import { writeFile } from 'node:fs/promises';
 
const doc = await coffrify.intakes.documents.retrieve('itk_123', 'doc_8f2a');
 
for (const file of doc.files) {
  const res = await fetch(file.download_url);
  const data = Buffer.from(await res.arrayBuffer());
  await writeFile(`./inbox/${file.id}-${file.name}`, data);
}

Si votre Réception est en chiffrement de bout en bout, les fichiers téléchargés sont chiffrés et la clé reste chez vous : le serveur ne peut pas lire le contenu. Vous les déchiffrez de votre côté avec votre clé. Le SDK Coffrify s'en charge pour vous. Conséquence directe : si vous perdez votre clé ou votre phrase secrète, personne ne peut récupérer les données. Conservez-les en lieu sûr et sauvegardez vos codes de récupération.

Réagir en temps réel avec les webhooks

Plutôt que d'interroger l'API en boucle, abonnez-vous aux webhooks de la famille request.* pour être notifié dès qu'un dépôt arrive. À la réception de l'événement, déclenchez votre traitement : récupérez le dépôt, téléchargez son contenu et classez-le. Le catalogue complet des événements est consultable publiquement via GET /v1/webhooks/events.

// Créer l'abonnement (scope webhooks:manage)
const hook = await coffrify.webhooks.create({
  url: 'https://exemple.com/coffrify/webhooks',
  events: ['request.submitted'],
});
// hook.secret (whsec_…) n'est montré qu'une fois : stockez-le.
 
// Côté réception de l'événement (Express)
app.post('/coffrify/webhooks', async (req, res) => {
  const { type, data } = req.body;
  if (type === 'request.submitted') {
    const doc = await coffrify.intakes.documents.retrieve(
      data.intake_id,
      data.document_id,
    );
    await traiter(doc);
  }
  res.sendStatus(200);
});

Rétention et RGPD

Les données sont hébergées en Union européenne et le traitement respecte le RGPD. En tant qu'intégrateur, vous restez maître du cycle de vie : une fois un dépôt récupéré et classé dans votre système, ne le laissez pas s'accumuler côté Réception au-delà de ce qui est nécessaire. Limitez la durée de conservation au strict besoin, et gardez la référence opaque comme seul lien vers l'identité réelle, qui reste chez vous.

• Récupérez les dépôts puis traitez-les rapidement : les URL de téléchargement sont volontairement de courte durée.
• Ne stockez jamais d'identité réelle ni de secret dans les métadonnées d'enveloppe, qui sont en clair ; servez-vous de la référence opaque.
• Pour une demande d'accès ou de portabilité d'une personne concernée, vous pouvez déclencher un export via POST /v1/gdpr/export (scope gdpr:export).
• Avant d'aller en production, validez tout le flux sur une clé cof_sandbox_… : environnement isolé, éphémère (24 h) et hors facturation.

En combinant la liste paginée, le filtrage par statut et par référence opaque, la récupération du contenu et les webhooks request.*, vous disposez d'un pipeline complet : Coffrify reçoit les documents de vos tiers, vous notifie, et vous les rapatriez dans vos dossiers, sans que la plateforme ne connaisse jamais l'identité réelle derrière chaque dépôt.