L'API Coffrify permet de déposer plusieurs fichiers en une seule opération grâce à un flux en deux étapes : vous créez d'abord le transfert en déclarant la liste des fichiers (nom, taille, type MIME), l'API vous renvoie pour chaque fichier une URL de mise en ligne présignée, puis vous effectuez un PUT direct sur cette URL. Le transfert n'est visible par les destinataires qu'une fois tous les fichiers déposés. Cette architecture garantit que vos données transitent directement entre votre client et le stockage chiffré, sans jamais passer par les serveurs Coffrify.
/v1/transfersCrée un nouveau transfert et retourne les URL de mise en ligne présignées pour chaque fichier déclaré.GET/v1/transfers/{id}/filesListe les fichiers attachés à un transfert : nom, taille, type MIME et chemin de stockage.Authentification
Les deux endpoints nécessitent une clé API dans l'en-tête Authorization: Bearer <clé>. La création d'un transfert requiert le scope transfers:write ; la lecture des fichiers requiert transfers:read. Vos clés sont préfixées cof_live_… en production, cof_test_… en mode test et cof_sandbox_… en environnement sandbox. En sandbox, des plafonds s'appliquent automatiquement : 10 fichiers par transfert, 10 Mo par fichier et 25 transferts par tranche de 24 heures.
Corps de la requête (POST /v1/transfers)
Le corps déclare la liste des fichiers à envoyer ; chaque entrée précise au minimum son name et sa size. Le tableau ci-dessous liste les champs acceptés.
| Champ | Type | Requis | Description |
|---|---|---|---|
| files | array | Oui | Tableau d'objets fichier. Chaque entrée doit contenir name, size (octets) et optionnellement mime_type. |
| files[].name | string | Oui | Nom du fichier tel qu'il sera affiché au destinataire. |
| files[].size | integer | Oui | Taille exacte en octets. Doit correspondre au fichier réel envoyé lors du PUT. |
| files[].mime_type | string | Non | Type MIME (ex. application/pdf). Défaut : application/octet-stream. |
| expires_in_hours | integer | Non | Durée de vie du lien en heures. Défaut selon votre plan. |
| max_downloads | integer | Non | Nombre maximum de téléchargements autorisés (plafonné à 5 en sandbox). |
| transfer_title | string | Non | Titre affiché sur la page de partage. |
| recipient | string | Non | Adresse e-mail du destinataire pour notification automatique. |
| password | string | Non | Mot de passe protégeant l'accès au transfert. |
| notes | string | Non | Message visible par le destinataire. |
| allow_download | boolean | Non | Autoriser le téléchargement des fichiers (défaut : true). |
| auto_delete | boolean | Non | Supprimer automatiquement le transfert après expiration. |
| custom_slug | string | Non | Slug personnalisé pour l'URL de partage (ex. mon-rapport-2026). |
| notify_opens | boolean | Non | Recevoir une notification à chaque ouverture du lien. |
| watermark_enabled | boolean | Non | Activer le filigrane sur les documents. |
| watermark_text | string | Non | Texte du filigrane (affiché si watermark_enabled est true). |
| geo_allowlist | array | Non | Codes pays ISO 3166-1 alpha-2 autorisant le téléchargement (ex. ["FR","DE"]). |
| geo_blocklist | array | Non | Codes pays bloqués. |
| scheduled_for | string (ISO 8601) | Non | Date de publication différée du transfert. |
| encryption_mode | string | Non | Mode de chiffrement (ex. aes-256-gcm). Défaut selon la configuration du workspace. |
Exemple complet (deux fichiers)
L'exemple ci-dessous envoie deux fichiers en une fois : on crée le transfert, puis on téléverse chaque fichier sur l'URL présignée correspondante via un PUT. Choisissez votre langage.
Réponse (POST /v1/transfers)
La réponse renvoie un objet transfer et un tableau upload_urls, une URL par fichier déclaré. Associez chaque URL au bon fichier (l'ordre suit celui de votre tableau files) avant de téléverser.
Réponse (GET /v1/transfers/{id}/files)
La liste des fichiers (data) confirme ce qui est effectivement stocké : nom, taille, type MIME. Utilisez-la pour vérifier que tous vos téléversements ont bien abouti.
Erreurs
Les erreurs portent surtout sur la validation du tableau files (taille manquante ou incohérente) et sur les scopes. Le tableau ci-dessous indique la correction à apporter.
| HTTP | Code | Quand | Résolution |
|---|---|---|---|
| 400 | validation_error | files[] absent ou tableau vide dans le corps de la requête. | Ajoutez au moins un objet dans le tableau files avec name et size. |
| 401 | missing_api_key | En-tête Authorization absent. | Ajoutez Authorization: Bearer cof_live_… à chaque requête. |
| 401 | invalid_api_key | Clé API invalide, révoquée ou expirée. | Vérifiez la clé dans votre tableau de bord et assurez-vous d'utiliser le bon préfixe (cof_live_, cof_test_ ou cof_sandbox_). |
| 403 | scope_missing | La clé API ne possède pas le scope transfers:write (POST) ou transfers:read (GET). | Regénérez la clé en cochant les scopes requis. |
| 403 | ip_not_allowed | L'IP appelante est hors de la liste blanche configurée sur la clé. | Ajoutez votre IP sortante dans les restrictions de la clé API. |
| 404 | not_found | Le transfer_id passé à /v1/transfers/{id}/files n'existe pas ou n'appartient pas au workspace. | Vérifiez l'identifiant renvoyé par le POST initial. |
| 422 | validation_error | En sandbox : plus de 10 fichiers ou un fichier dépasse 10 Mo. | Réduisez le nombre de fichiers ou leur taille, ou passez en clé cof_live_…. |
| 429 | rate_limited | Quota de requêtes par minute dépassé, ou 25 transferts sandbox sur 24 h atteints. | Attendez la durée indiquée dans l'en-tête Retry-After avant de réessayer. |
| 500 | internal_error | Erreur interne lors de la génération des URL présignées. | Consultez X-Request-Id dans la réponse et contactez le support avec cet identifiant. |