Modèles de transfert

Enregistrez vos options de transfert (expiration, mot de passe, filigrane, pays autorisés) dans des modèles réutilisables via /v1/templates, puis appliquez-les pour créer des transferts pré-remplis en un appel.

Un modèle de transfert est un jeu d'options enregistré une fois et réutilisé à volonté. Plutôt que de répéter l'expiration, le mot de passe, le filigrane ou la liste de pays autorisés à chaque envoi, vous les définissez dans un modèle, puis vous l'appliquez pour créer un transfert pré-rempli. Les modèles vivent au niveau de l'espace de travail et sont gérés via /v1/templates. La lecture requiert le scope templates:read, la création et la modification requièrent templates:manage, et l'application d'un modèle (qui crée un vrai transfert) requiert transfers:write.

Les options d'un modèle

Un modèle porte un nom et une description, plus l'ensemble des réglages qui seront copiés dans chaque transfert créé à partir de lui. Le tableau ci-dessous liste les champs que vous pouvez définir. Tous sont optionnels sauf name.

Champ	Type	Description
name	string	Nom du modèle. Obligatoire.
description	string	Description libre, pour vos équipes.
is_default	boolean	Marque ce modèle comme modèle par défaut de l'espace.
expires_in_hours	number	Durée de validité du transfert, en heures. Minimum 1. Par défaut 48.
max_downloads	number \| null	Nombre maximal de téléchargements. `null` = illimité.
password_enabled	boolean	Active la protection par mot de passe.
password	string \| null	Mot de passe à appliquer au transfert.
watermark_enabled	boolean	Active le filigrane sur les documents pris en charge.
watermark_text	string \| null	Texte du filigrane.
burn_after_read	boolean	Détruit le transfert après la première lecture.
geo_allowlist	string[] \| null	Codes pays ISO autorisés à accéder (ex. `["FR","BE"]`).
require_signature	boolean	Exige une signature du destinataire.
require_email_verification	boolean	Exige la vérification de l'adresse e-mail du destinataire.
approval_required	boolean	Soumet l'accès à une approbation.
allow_reply	boolean	Autorise le destinataire à répondre avec des fichiers.
custom_message	string \| null	Message affiché au destinataire.
notification_email	string \| null	Adresse notifiée des évènements du transfert.
encryption_mode	string	Mode de chiffrement. `server_side` par défaut.

Lister les modèles

Renvoie tous les modèles de l'espace de travail, du plus récent au plus ancien, sous la forme d'une liste.

GET/v1/templatesLister les modèles de transfert (scope templates:read).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { data } = await coffrify.templates.list();
for (const tpl of data) {
  console.log(tpl.id, tpl.name, `${tpl.expires_in_hours} h`);
}

Créer un modèle

Fournissez au minimum un name. Les champs non précisés prennent leurs valeurs par défaut (par exemple expires_in_hours vaut 48). S'agissant d'une écriture, vous pouvez transmettre un en-tête Idempotency-Key pour rejouer la requête sans créer de doublon.

POST/v1/templatesCréer un modèle de transfert (scope templates:manage).

const tpl = await coffrify.templates.create({
  name: 'Contrats clients',
  description: 'Envoi protégé avec filigrane',
  expires_in_hours: 168,
  max_downloads: 3,
  password_enabled: true,
  password: 'Confiden4tiel!',
  watermark_enabled: true,
  watermark_text: 'Confidentiel - Coffrify',
  geo_allowlist: ['FR', 'BE', 'LU'],
});
 
console.log(tpl.id);

Récupérer, modifier ou supprimer un modèle

GET /v1/templates/{id} renvoie un modèle. PATCH /v1/templates/{id} met à jour uniquement les champs transmis : pour effacer une valeur, passez null (sur max_downloads, password ou geo_allowlist). DELETE /v1/templates/{id} supprime le modèle et renvoie { "id": "...", "object": "transfer_template", "deleted": true }. Un identifiant inconnu renvoie une erreur not_found.

// Allonger l'expiration et retirer le plafond de téléchargements
const updated = await coffrify.templates.update('tpl_123', {
  expires_in_hours: 336,
  max_downloads: null,
});
 
// Supprimer
await coffrify.templates.delete('tpl_123');

Appliquer un modèle pour créer un transfert

C'est l'intérêt principal : POST /v1/templates/{id}/apply crée un transfert pré-rempli avec les options du modèle. Fournissez le tableau files (chaque entrée a name, size et mime_type facultatif), éventuellement un recipient, et un objet overrides pour ajuster ponctuellement certaines options sans modifier le modèle. Cet appel requiert le scope transfers:write. La réponse contient le transfert créé, les URL d'envoi par fichier et le lien de partage.

POST/v1/templates/{id}/applyCréer un transfert à partir d'un modèle (scope transfers:write).

const result = await coffrify.templates.apply('tpl_123', {
  files: [
    { name: 'devis.pdf', size: 482113, mime_type: 'application/pdf' },
  ],
  recipient: 'client@exemple.fr',
  overrides: {
    expires_in_hours: 24, // exceptionnellement plus court
  },
});
 
console.log(result.share_url);
// Téléversez ensuite chaque fichier vers result.upload_urls[i].url
for (const u of result.upload_urls) {
  console.log(u.file_id, u.url);
}

Exemple de réponse renvoyée par l'application d'un modèle :

{
  "transfer": {
    "id": "trf_8f2a...",
    "short_code": "a1B2c3",
    "expires_at": "2026-06-11T14:32:00Z"
  },
  "upload_urls": [
    { "file_id": "devis.pdf", "url": "https://..." }
  ],
  "share_url": "https://files.coffrify.com/a1B2c3"
}

Bonnes pratiques

Nommez vos modèles par usage métier (« Contrats clients », « Diffusion presse », « Pièces sensibles ») pour que vos équipes appliquent le bon sans réfléchir aux options.
Marquez le plus courant avec is_default afin qu'il serve de base aux nouveaux envois.
Réservez les surcharges aux exceptions ponctuelles ; si un réglage change durablement, modifiez le modèle avec PATCH plutôt que de surcharger à chaque appel.
Limitez templates:manage aux clés qui doivent réellement créer ou modifier des modèles ; une clé de simple lecture se contente de templates:read.