Construire un portail client

Un portail client est un espace unique, propre à votre marque, où un client retrouve tous les fichiers que vous lui adressez. Plutôt que d'envoyer des liens isolés, vous regroupez vos transferts dans une collection (/v1/collections), vous habillez la page partagée avec votre logo et vos couleurs, puis vous diffusez l'ensemble sous votre propre domaine. Cette recette vous guide pas à pas : créer la collection, y rattacher des transferts, gérer l'expiration, et associer le tout à votre marque et à un domaine personnalisé. Tous les appels utilisent la base https://api.coffrify.com/v1 et l'en-tête Authorization: Bearer <clé>.

Vue d'ensemble

Le portail repose sur trois briques que vous assemblez une fois pour chaque client. La collection sert de conteneur logique et porte l'URL partagée. Les transferts sont les livraisons individuelles que vous y ajoutez au fil de l'eau. Le branding et le domaine personnalisé donnent à la page un aspect cohérent avec votre identité. Vous créez la collection au démarrage de la relation, puis vous l'alimentez aussi souvent que nécessaire.

• Collection : l'espace partagé et son lien permanent (name, slug, description, expires_at).
• Transferts : chaque jeu de fichiers chiffrés, rattaché à la collection.
• Branding et domaine : logo, couleurs et adresse à vos couleurs, configurés depuis votre espace de travail.

Étape 1 : créer la collection du client

Commencez par créer une collection qui représente l'espace du client. Le slug détermine la partie lisible de l'URL partagée : choisissez-le stable et explicite, par exemple le nom du client. Vous pouvez fixer une date d'expiration globale avec expires_at (date ISO 8601), au-delà de laquelle le portail n'est plus accessible.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const collection = await coffrify.collections.create({
  name: 'Espace Dupont & Associés',
  slug: 'dupont-associes',
  description: 'Livraisons et documents partagés avec Dupont & Associés.',
  expires_at: '2026-12-31T23:59:59Z'
});
 
console.log(collection.id);

Étape 2 : ajouter des transferts à la collection

Chaque livraison est un transfert classique. Vous créez le transfert avec la liste des fichiers, vous téléversez le contenu via les upload_urls retournées, puis vous rattachez le transfert à la collection du client. Un transfer_title clair aide le client à s'y retrouver dans le portail.

// 1. Créer le transfert
const { transfer, upload_urls } = await coffrify.transfers.create({
  files: [{ name: 'rapport-q2.pdf', size: 482113, mime_type: 'application/pdf' }],
  transfer_title: 'Rapport trimestriel Q2',
  expires_in_hours: 168,
  collection_id: collection.id
});
 
// 2. Téléverser chaque fichier vers son URL signée (PUT)
const slot = upload_urls[0];
await fetch(slot.url, {
  method: 'PUT',
  headers: slot.headers,
  body: fileBuffer
});
 
console.log(transfer.share_url);

Le téléversement se fait toujours en PUT vers l'URL signée, en reprenant les headers fournis. Le transfert apparaît ensuite dans la collection. Répétez cette étape à chaque nouvelle livraison : le client retrouve toutes ses remises au même endroit, sans nouveau lien à mémoriser.

Étape 3 : appliquer votre marque

Le branding s'applique au niveau de votre espace de travail et habille automatiquement les pages partagées : logo, couleur d'accent et nom affiché. Configurez-le depuis votre tableau de bord, rubrique Marque. Si vous pilotez ces réglages par API, le scope branding:manage est requis. Une fois la marque définie, toutes vos collections et transferts en héritent : la page que voit le client porte votre identité, pas une page générique.

Étape 4 : diffuser sous un domaine personnalisé

Pour que l'URL du portail porte votre propre nom de domaine plutôt que coffrify.com, ajoutez et vérifiez un domaine personnalisé depuis votre espace de travail, rubrique Domaines. Vous déclarez un sous-domaine (par exemple partage.votreentreprise.fr), vous ajoutez l'enregistrement DNS indiqué, puis vous attendez la vérification. La gestion par API requiert le scope domains:manage. Une fois le domaine actif, les share_url de vos collections et transferts sont servies sous cette adresse.

Étape 5 : partager et suivre l'activité

Communiquez au client l'URL de la collection : c'est son point d'entrée permanent. Pour suivre ce qui s'y passe sans interroger l'API en boucle, abonnez-vous aux webhooks. Vous serez notifié à chaque téléchargement et à chaque évolution de la collection, ce qui permet par exemple de relancer un client ou d'archiver une livraison consommée.

await coffrify.webhooks.create({
  url: 'https://votreentreprise.fr/hooks/coffrify',
  events: [
    'transfer.downloaded',
    'transfer.expired',
    'collection.updated'
  ]
});

Chaque webhook est signé avec un secret whsec_ retourné à la création : vérifiez cette signature côté serveur avant de traiter l'événement. Vous pouvez consulter la liste complète des types d'événements publiquement via GET /v1/webhooks/events.