SDK quickstarts

Cette page vous fait passer de zéro à un premier transfert chiffré en quelques minutes. La règle est simple : un seul SDK officiel existe aujourd'hui, le SDK JavaScript/Node (package coffrify). Pour les autres langages (Python, Go, Ruby, PHP, Rust, Java, .NET), les bibliothèques sont en cours de préparation. En attendant, l'API REST v1 reste pleinement utilisable depuis n'importe quel langage : nous montrons donc l'appel HTTP direct, dans l'idiome de chaque langage, pour que vous puissiez démarrer dès maintenant sans attendre un SDK. Tous les exemples ci-dessous ciblent la même base, https://api.coffrify.com/v1, et s'authentifient par un en-tête Authorization: Bearer <clé>.

Avant de commencer

Récupérez une clé d'API dans votre tableau de bord. Utilisez une clé cof_test_… pour vos essais (elle n'envoie pas de notifications réelles), une clé cof_sandbox_… pour un bac à sable isolé qui expire au bout de 24 h, et une clé cof_live_… une fois en production. La clé doit porter le scope transfers:write pour créer des transferts. Ne committez jamais une clé en clair : passez-la par une variable d'environnement, par exemple COFFRIFY_API_KEY.

Démarrage express avec le SDK Node

Installez le package, instanciez le client avec votre clé, puis créez un transfert. La méthode coffrify.transfers.create renvoie l'objet transfer, la liste des upload_urls (une par fichier) et le lien de partage share_url. Le flux complet tient en trois temps : on crée le transfert, on téléverse chaque fichier en PUT vers son URL signée, puis on partage share_url avec le destinataire.

$ npm i @coffrify/sdk

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
// 1. Créer le transfert
const { transfer, upload_urls, share_url } = await coffrify.transfers.create({
  files: [{ name: 'rapport.pdf', size: 482311, mime_type: 'application/pdf' }],
  expires_in_hours: 168,        // 7 jours
  max_downloads: 3,
  transfer_title: 'Rapport trimestriel',
});
 
// 2. Téléverser chaque fichier vers son URL signée (PUT)
import { readFile } from 'node:fs/promises';
const bytes = await readFile('./rapport.pdf');
 
for (const part of upload_urls) {
  await fetch(part.url, { method: 'PUT', headers: part.headers, body: bytes });
}
 
// 3. Partager le lien
console.log('Statut   :', transfer.status);
console.log('Code     :', transfer.short_code);
console.log('Expire le:', transfer.expires_at);
console.log('Partage  :', share_url); // https://files.coffrify.com/<short_code>

Lister, récupérer et supprimer

Le SDK couvre aussi la lecture et la gestion. Les méthodes reflètent les endpoints REST : list pour parcourir vos transferts (pagination par curseur, limit jusqu'à 100), get pour en lire un, delete pour le révoquer immédiatement.

// Lister (pagination par curseur)
const page = await coffrify.transfers.list({ limit: 20 });
 
// Récupérer un transfert précis
const one = await coffrify.transfers.get(transfer.id);
 
// Supprimer / révoquer un transfert
await coffrify.transfers.delete(transfer.id);

Les autres langages : appel REST direct

En attendant les SDK dédiés, voici le même premier appel (créer un transfert) en HTTP direct. C'est exactement la requête que le SDK Node effectue sous le capot : un POST JSON vers /v1/transfers avec votre clé en Bearer. La réponse contient transfer, upload_urls et share_url ; il vous reste à téléverser chaque fichier en PUT vers l'URL fournie, puis à partager share_url.

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer $COFFRIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "files": [{ "name": "rapport.pdf", "size": 482311, "mime_type": "application/pdf" }],
    "expires_in_hours": 168,
    "max_downloads": 3,
    "transfer_title": "Rapport trimestriel"
  }'
 
# La réponse contient share_url et upload_urls[].url
# Téléversez ensuite chaque fichier :
# curl -X PUT "<upload_urls[0].url>" \
#   -H "Content-Type: application/pdf" \
#   --data-binary @rapport.pdf

Rejouer une création en toute sécurité

Sur toutes les écritures, envoyez un en-tête Idempotency-Key (de 8 à 255 caractères, unique par opération métier). Si la requête est rejouée, par exemple après un timeout réseau, l'API renvoie la réponse d'origine au lieu de créer un second transfert, et signale le rejeu par l'en-tête X-Coffrify-Idempotent-Replay: true. Pensez à surveiller aussi les en-têtes de quota X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; en cas de 429, respectez le délai indiqué par Retry-After.

Forme des erreurs

Toutes les erreurs partagent une enveloppe stable. Le champ code est lisible par machine, message est destiné aux humains, et request_id vous permet de retrouver la requête côté Coffrify si vous nous contactez.

{
  "error": {
    "code": "scope_missing",
    "message": "This token is missing the `transfers:write` scope.",
    "request_id": "req_8s2k…"
  }
}

Vous avez maintenant un transfert chiffré créé et partagé, en Node avec le SDK ou en REST direct pour les autres langages. La même mécanique (créer, téléverser, partager) s'applique partout, et votre code REST d'aujourd'hui restera valable lorsque les SDK Python, Go, Ruby, PHP, Rust, Java et .NET seront publiés.