Requête exemple
Réponse exemple
Génère une (ou plusieurs) URL S3 présignée de téléchargement direct pour les fichiers d'un transfert, sans passer par la page de partage publique ni la grille de mot de passe. L'URL pointe directement sur le bucket Scaleway coffrify-transfer (région fr-par) et est signée en AWS Signature V4 côté serveur. Comportement notable : ce téléchargement est de type administrateur/agent, il n'incrémente PAS le compteur total_downloads du transfert. Si le champ file_id est omis, l'endpoint renvoie une URL par fichier du transfert ; s'il est fourni, il ne signe que le fichier ciblé. Chaque URL force le téléchargement via un en-tête Content-Disposition: attachment reprenant le nom de fichier original.
Authentification
Requiert une clé API (cof_live_… / cof_test_…, restreinte cof_rk_… ou jeton MCP cof_mcp_…) portant le scope transfers:download. Le contrôle d'accès est portée par espace de travail : seul un transfert appartenant au workspace_id de la clé est résolu, tout autre identifiant renvoie 404. Si le scope manque, l'API répond 403 scope_missing.
Corps de la requête
Le corps JSON est entièrement optionnel : un POST sans corps signe tous les fichiers du transfert avec une expiration par défaut d'une heure.
| Champ | Type | Requis | Description |
|---|---|---|---|
| file_id | string | Non | Identifiant d'un fichier précis du transfert. Si omis (ou non-string), une URL est générée pour chaque fichier du transfert. Si fourni mais introuvable dans ce transfert, renvoie 404. |
| expires_in_seconds | number | Non | Durée de validité de l'URL présignée, en secondes. Valeur entière. Par défaut 3600 (1 h). Bornée automatiquement entre 60 et 86400 (24 h) : toute valeur hors bornes est ramenée dans l'intervalle, sans erreur. |
Réponse
Renvoie transfer_id et short_code du transfert, la durée expires_in_seconds réellement appliquée (après bornage) et expires_at (horodatage ISO 8601 d'expiration calculé côté serveur). Le tableau files contient un objet par fichier signé, avec file_id, file_name, file_size (octets), file_type (type MIME) et download_url (URL S3 présignée complète, directement utilisable en GET). Le champ note rappelle que ces URL contournent la passerelle de partage public et le mot de passe, et n'incrémentent pas le compteur de téléchargements : usage opérationnel admin/agent uniquement.
Erreurs
| Code HTTP | Code | Quand | Comment résoudre |
|---|---|---|---|
| 401 | missing_api_key / invalid_api_key | En-tête Authorization absent ou clé non reconnue. | Envoyer Authorization: Bearer cof_live_… avec une clé valide. |
| 403 | scope_missing | La clé n'a pas le scope transfers:download. | Émettre une nouvelle clé avec le scope transfers:download depuis app.coffrify.com/developer (ou /mcp pour un jeton MCP). |
| 404 | not_found | Transfert inexistant ou hors de l'espace de travail, OU file_id introuvable dans ce transfert, OU transfert sans fichier. | Vérifier l'id du transfert et le file_id. Confirmer que le transfert appartient à l'espace de la clé. |
| 410 | not_found | Le transfert existe mais son status vaut deleted. | Le transfert a été supprimé : aucune URL ne peut être générée. |
| 429 | rate_limited | Quota de requêtes/minute de l'espace de travail dépassé. | Respecter l'en-tête Retry-After et réessayer après la fenêtre. |
| 503 | internal_error | Identifiants Scaleway non configurés sur ce déploiement (SCALEWAY_ACCESS_KEY/SCALEWAY_SECRET_KEY manquants). | Erreur d'infrastructure côté Coffrify : contacter le support, non corrigeable côté client. |
Voir aussi
GET/v1/transfers/{id}Récupère les métadonnées d'un transfert et la liste de ses fichiers (file_id à passer ici).GET/v1/transfersListe paginée des transferts de l'espace de travail pour retrouver l'id cible.POST/v1/transfersCrée un transfert et ses fichiers en amont du flux de signature d'URL.