Créer et partager un transfert chiffré

Un transfert Coffrify est un conteneur chiffré (AES-256-GCM côté serveur, optionnel E2E) qui regroupe un ou plusieurs fichiers derrière un lien de partage unique de la forme https://files.coffrify.com/<short_code>. La création se fait en deux phases distinctes : (1) vous appelez POST /v1/transfers pour créer le transfert et obtenir des URLs de téléversement présignées par Scaleway S3, (2) vous uploadez directement chaque fichier sur son URL présignée via un simple PUT. Une fois l'upload confirmé, vous pouvez envoyer le lien au destinataire ou déclencher l'envoi de l'e-mail de notification depuis l'API.

Authentification

Tous les appels doivent inclure votre clé API dans l'en-tête Authorization: Bearer <cle>. Pour créer ou modifier un transfert, la clé doit posséder le scope transfers:write. Pour lire la liste ou les détails, le scope transfers:read suffit. Pour générer des URLs de téléchargement signées côté administration, le scope transfers:download est requis. Les clés de test commencent par cof_test_…, les clés de production par cof_live_… et les clés sandbox par cof_sandbox_…. L'environnement de la clé détermine l'isolation des données : une clé cof_sandbox_… ne voit et ne crée que des transferts sandbox, plafonnés à 10 Mo par fichier, 10 fichiers par transfert et 25 transferts par 24 heures.

Corps de la requête, POST /v1/transfers

Seul le tableau files est obligatoire : chaque entrée déclare le name, la size en octets et, idéalement, le mime_type. Tous les autres champs sont facultatifs et activent des options de sécurité ou de cycle de vie (mot de passe, expiration, plafond de téléchargements, restrictions géographiques, chiffrement de bout en bout). Vous pouvez donc commencer avec une requête minimale, puis ajouter les options au besoin.

Exemple complet en quatre étapes

L'exemple ci-dessous déroule un partage complet en quatre appels : (1) créer le transfert et récupérer les URLs présignées, (2) téléverser le fichier directement sur le stockage via un PUT, (3) vérifier le statut du transfert, puis (4) envoyer l'e-mail de partage au destinataire. Les quatre onglets réalisent exactement la même chose dans votre langage.

# ETAPE 1 : Créer le transfert et obtenir les URLs présignées
curl -s -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_title": "Rapport Q2 2026",
    "expires_in_hours": 72,
    "max_downloads": 3,
    "password": "s3cr3t!",
    "recipient": "alice@acme.com",
    "files": [
      { "name": "rapport-q2.pdf", "size": 245760, "mime_type": "application/pdf" }
    ]
  }' > /tmp/transfer.json
 
# Extraire l'URL d'upload et le lien de partage
UPLOAD_URL=$(jq -r '.upload_urls[0].url' /tmp/transfer.json)
SHARE_URL=$(jq -r '.share_url' /tmp/transfer.json)
 
# ETAPE 2 : Uploader le fichier directement sur l'URL présignée (PUT S3)
curl -s -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --upload-file rapport-q2.pdf
 
# ETAPE 3 : Vérifier le statut du transfert
TRANSFER_ID=$(jq -r '.transfer.id' /tmp/transfer.json)
curl -s -X GET "https://api.coffrify.com/v1/transfers/$TRANSFER_ID" \
  -H "Authorization: Bearer cof_live_…"
 
# ETAPE 4 : (Re)envoyer l'e-mail de partage à un destinataire
curl -s -X POST "https://api.coffrify.com/v1/transfers/$TRANSFER_ID/email" \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@acme.com",
    "subject": "Votre rapport Q2 est disponible",
    "message": "Bonjour, veuillez trouver ci-joint le rapport Q2 2026."
  }'

Le point clé est la séparation en deux temps : l'API ne reçoit jamais vos fichiers, elle vous renvoie des URLs présignées sur lesquelles vous téléversez vous-même. Dès que le PUT de l'étape 2 réussit, le fichier est disponible derrière share_url et le lien peut être transmis.

Réponse, POST /v1/transfers (201 Created)

La réponse de création contient trois éléments à retenir : upload_urls, le ou les liens présignés à utiliser immédiatement pour le téléversement ; share_url, le lien public à transmettre au destinataire ; et transfer.id, l'identifiant à réutiliser pour toutes les opérations suivantes.

{
  "transfer": {
    "id": "b7c3e2a1-4d5f-4a2b-9c1e-0f8d3e7a2b1c",
    "short_code": "rp2026q2",
    "transfer_title": "Rapport Q2 2026",
    "status": "active",
    "expires_at": "2026-06-09T14:32:00.000Z",
    "max_downloads": 3,
    "total_downloads": 0,
    "scan_status": "pending",
    "encryption_mode": "server",
    "created_at": "2026-06-06T14:32:00.000Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport-q2.pdf",
      "url": "https://coffrify-transfer.s3.fr-par.scw.cloud/b7c3e2a1-4d5f/rapport-q2.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Expires=3600&X-Amz-Signature=…",
      "headers": {
        "Content-Type": "application/pdf"
      }
    }
  ],
  "share_url": "https://files.coffrify.com/rp2026q2",
  "totp_secret": null
}

Réponse, GET /v1/transfers/{id} (200 OK)

La lecture d'un transfert reflète son état courant. Surveillez scan_status (pending puis clean une fois l'analyse antivirus terminée) et total_downloads, qui s'incrémente à chaque téléchargement jusqu'au plafond max_downloads.

{
  "id": "b7c3e2a1-4d5f-4a2b-9c1e-0f8d3e7a2b1c",
  "short_code": "rp2026q2",
  "transfer_title": "Rapport Q2 2026",
  "status": "active",
  "expires_at": "2026-06-09T14:32:00.000Z",
  "max_downloads": 3,
  "total_downloads": 1,
  "scan_status": "clean",
  "encryption_mode": "server",
  "is_password_protected": true,
  "folder_id": null,
  "workspace_id": "ws_01hx…",
  "created_at": "2026-06-06T14:32:00.000Z",
  "files": [
    {
      "id": "f1a2b3c4-…",
      "file_name": "rapport-q2.pdf",
      "file_size": 245760,
      "file_type": "application/pdf",
      "created_at": "2026-06-06T14:32:01.000Z"
    }
  ]
}

Réponse, POST /v1/transfers/{id}/email (202 Accepted)

L'envoi d'e-mail est asynchrone : l'API répond 202 Accepted avec un delivery_status à sent dès que le message est pris en charge. Vous pouvez relancer cet appel autant de fois que nécessaire pour notifier d'autres destinataires.

{
  "transfer_id": "b7c3e2a1-4d5f-4a2b-9c1e-0f8d3e7a2b1c",
  "short_code": "rp2026q2",
  "share_url": "https://files.coffrify.com/rp2026q2",
  "sent_to": "alice@acme.com",
  "subject": "Votre rapport Q2 est disponible",
  "delivery_status": "sent",
  "note": null
}

Erreurs

La plupart des erreurs sont soit des problèmes de validation du corps de requête (400 et 422), soit d'authentification ou de scope (401 et 403). Le tableau ci-dessous indique, pour chaque cas, quand il survient et comment le corriger.

Voir aussi

• Obtenir une URL de téléchargement signée
• Cloner ou étendre un transfert
• Approuver un transfert (workflow)
• Créer un transfert avec options avancées
• Agent de transfert automatique
• Lire les codes d'erreur API
• Référence : POST /v1/transfers
• Référence : GET /v1/transfers/{id}
• Référence : POST /v1/transfers/{id}/email