Votre premier transfert chiffré

Un transfert est l'unité centrale de Coffrify : il regroupe un ou plusieurs fichiers chiffrés (AES-256-GCM côté stockage), une date d'expiration, un quota de téléchargements et un lien de partage unique. Ce guide vous montre comment créer votre premier transfert via l'API, obtenir les URLs d'upload présignées, déposer vos fichiers sur l'objet de stockage, puis récupérer le lien public à partager. Le flux complet repose sur trois étapes : POST /v1/transfers (création), PUT vers les URLs présignées (upload), et lecture du champ share_url dans la réponse.

Authentification

Toutes les requêtes de création ou de lecture de transferts exigent une clé API transmise dans l'en-tête Authorization: Bearer <clé>. Le scope requis est transfers:write pour la création et la suppression, et transfers:read pour la liste et la lecture. Pour générer des URLs de téléchargement côté administration (sans incrémenter le compteur), le scope transfers:download est nécessaire. Créez ou consultez vos clés dans la console Coffrify.

Corps de la requête

Exemples d'appel

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_test_votreclé" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "files": [
      { "name": "rapport-annuel.pdf", "size": 204800, "mime_type": "application/pdf" }
    ],
    "transfer_title": "Rapport annuel 2026",
    "expires_in_hours": 72,
    "max_downloads": 3,
    "recipient": "destinataire@exemple.com"
  }'

Réponse

En cas de succès, l'API retourne un HTTP 201 avec l'objet suivant. Le champ upload_urls contient une entrée par fichier déclaré : vous devez effectuer un PUT vers chaque url avec les en-têtes headers fournis. Le champ share_url est le lien public prêt à être transmis au destinataire.

{
  "transfer": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_code": "xK9mPq",
    "transfer_title": "Rapport annuel 2026",
    "status": "active",
    "expires_at": "2026-06-09T14:32:00.000Z",
    "max_downloads": 3,
    "total_downloads": 0,
    "scan_status": "pending",
    "encryption_mode": "managed",
    "created_at": "2026-06-06T14:32:00.000Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport-annuel.pdf",
      "url": "https://coffrify-transfer.s3.fr-par.scw.cloud/a1b2c3d4/rapport-annuel.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Expires=900&X-Amz-Signature=...",
      "headers": {
        "Content-Type": "application/pdf"
      }
    }
  ],
  "share_url": "https://files.coffrify.com/xK9mPq",
  "totp_secret": null
}

Récupérer un transfert existant

Après avoir uploadé vos fichiers, vous pouvez vérifier l'état du transfert (notamment le scan_status mis à jour par l'antivirus asynchrone) via GET /v1/transfers/{id}. La réponse inclut le champ files avec les métadonnées de chaque fichier (id, file_name, file_size, file_type, created_at).

$ curl https://api.coffrify.com/v1/transfers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer cof_test_votreclé"

Obtenir une URL de téléchargement admin

Pour récupérer un fichier côté serveur (agent, automatisation, archivage) sans passer par le lien public ni incrémenter le compteur total_downloads, utilisez POST /v1/transfers/{id}/download-url. Le scope requis est transfers:download. Vous pouvez cibler un fichier précis via file_id, ou omettre ce champ pour obtenir une URL par fichier. Le paramètre expires_in_seconds contrôle la durée de validité de l'URL présignée (60 à 86400 secondes, défaut 3600).

// POST /v1/transfers/{id}/download-url
// Body : { "file_id": "uuid-du-fichier", "expires_in_seconds": 3600 }
 
// Réponse :
{
  "transfer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "short_code": "xK9mPq",
  "expires_in_seconds": 3600,
  "expires_at": "2026-06-06T15:32:00.000Z",
  "files": [
    {
      "file_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
      "file_name": "rapport-annuel.pdf",
      "file_size": 204800,
      "file_type": "application/pdf",
      "download_url": "https://coffrify-transfer.s3.fr-par.scw.cloud/a1b2c3d4/rapport-annuel.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
    }
  ],
  "note": "These URLs bypass the public share + password gate AND do NOT increment total_downloads. For admin/agent operational use only."
}

Idempotence

L'API Coffrify supporte l'idempotence sur les requêtes POST. Envoyez un en-tête Idempotency-Key: <uuid> unique par tentative logique. Si la même clé est rejouée dans la fenêtre de validité, vous recevez la réponse originale avec l'en-tête X-Coffrify-Idempotent-Replay: true, sans créer de doublon. C'est indispensable en cas de timeout réseau ou de retry automatique dans votre pipeline.

Erreurs

Voir aussi

• Référence POST /v1/transfers
• Référence GET /v1/transfers/{id}
• Référence DELETE /v1/transfers/{id}
• Référence POST /v1/transfers/{id}/download-url
• Premiers pas avec l'API
• Gestion des dossiers
• Webhooks : être notifié des événements
• Rate limits et quotas
• Gestion des erreurs