💻
SDK & CLI·Débutant·8 min

Uploader des fichiers en batch avec le CLI coffrify

Créez un transfert multi-fichiers en une seule requête POST, récupérez les URL de mise en ligne signées, déposez chaque fichier directement dans le stockage, puis vérifiez l'inventaire via l'endpoint dédié.

Télécharger en PDF

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.

POST/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.

ChampTypeRequisDescription
filesarrayOuiTableau d'objets fichier. Chaque entrée doit contenir name, size (octets) et optionnellement mime_type.
files[].namestringOuiNom du fichier tel qu'il sera affiché au destinataire.
files[].sizeintegerOuiTaille exacte en octets. Doit correspondre au fichier réel envoyé lors du PUT.
files[].mime_typestringNonType MIME (ex. application/pdf). Défaut : application/octet-stream.
expires_in_hoursintegerNonDurée de vie du lien en heures. Défaut selon votre plan.
max_downloadsintegerNonNombre maximum de téléchargements autorisés (plafonné à 5 en sandbox).
transfer_titlestringNonTitre affiché sur la page de partage.
recipientstringNonAdresse e-mail du destinataire pour notification automatique.
passwordstringNonMot de passe protégeant l'accès au transfert.
notesstringNonMessage visible par le destinataire.
allow_downloadbooleanNonAutoriser le téléchargement des fichiers (défaut : true).
auto_deletebooleanNonSupprimer automatiquement le transfert après expiration.
custom_slugstringNonSlug personnalisé pour l'URL de partage (ex. mon-rapport-2026).
notify_opensbooleanNonRecevoir une notification à chaque ouverture du lien.
watermark_enabledbooleanNonActiver le filigrane sur les documents.
watermark_textstringNonTexte du filigrane (affiché si watermark_enabled est true).
geo_allowlistarrayNonCodes pays ISO 3166-1 alpha-2 autorisant le téléchargement (ex. ["FR","DE"]).
geo_blocklistarrayNonCodes pays bloqués.
scheduled_forstring (ISO 8601)NonDate de publication différée du transfert.
encryption_modestringNonMode 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.

# ÉTAPE 1 : Créer le transfert et récupérer les URL présignées
RESPONSE=$(curl -s -X POST https://api.coffrify.com/v1/transfers \
-H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"transfer_title": "Rapport annuel 2026",
"expires_in_hours": 72,
"max_downloads": 10,
"recipient": "client@example.com",
"files": [
{ "name": "rapport.pdf", "size": 204800, "mime_type": "application/pdf" },
{ "name": "annexes.xlsx", "size": 51200, "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }
]
}')
 
echo $RESPONSE | python3 -m json.tool
 
# ÉTAPE 2 : Extraire les URL présignées et uploader chaque fichier
URL_1=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_urls'][0]['url'])")
URL_2=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_urls'][1]['url'])")
 
curl -s -X PUT "$URL_1" \
-H "Content-Type: application/pdf" \
--upload-file ./rapport.pdf
 
curl -s -X PUT "$URL_2" \
-H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
--upload-file ./annexes.xlsx
 
# ÉTAPE 3 : Vérifier les fichiers du transfert
TRANSFER_ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['transfer']['id'])")
 
curl -s https://api.coffrify.com/v1/transfers/$TRANSFER_ID/files \
-H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" | python3 -m json.tool

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.

{
"transfer": {
"id": "tr_01HXYZ1234567890ABCDEFGHIJ",
"short_code": "abc123",
"transfer_title": "Rapport annuel 2026",
"status": "pending",
"expires_at": "2026-06-09T14:32:00.000Z",
"max_downloads": 10,
"total_downloads": 0,
"scan_status": "pending",
"encryption_mode": "aes-256-gcm",
"created_at": "2026-06-06T14:32:00.000Z"
},
"upload_urls": [
{
"file_id": "rapport.pdf",
"url": "https://storage.coffrify.com/uploads/tr_01HXYZ.../rapport.pdf?X-Amz-Signature=...",
"headers": {
"Content-Type": "application/pdf"
}
},
{
"file_id": "annexes.xlsx",
"url": "https://storage.coffrify.com/uploads/tr_01HXYZ.../annexes.xlsx?X-Amz-Signature=...",
"headers": {
"Content-Type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}
}
],
"share_url": "https://files.coffrify.com/abc123",
"totp_secret": null
}

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.

{
"transfer_id": "tr_01HXYZ1234567890ABCDEFGHIJ",
"short_code": "abc123",
"object": "list",
"data": [
{
"id": "file_01HXYZ111",
"file_name": "rapport.pdf",
"file_size": 204800,
"file_type": "application/pdf",
"storage_path": "uploads/tr_01HXYZ.../rapport.pdf",
"created_at": "2026-06-06T14:32:05.000Z"
},
{
"id": "file_01HXYZ222",
"file_name": "annexes.xlsx",
"file_size": 51200,
"file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"storage_path": "uploads/tr_01HXYZ.../annexes.xlsx",
"created_at": "2026-06-06T14:32:07.000Z"
}
],
"file_count": 2,
"total_bytes": 256000
}

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.

HTTPCodeQuandRésolution
400validation_errorfiles[] absent ou tableau vide dans le corps de la requête.Ajoutez au moins un objet dans le tableau files avec name et size.
401missing_api_keyEn-tête Authorization absent.Ajoutez Authorization: Bearer cof_live_… à chaque requête.
401invalid_api_keyClé 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_).
403scope_missingLa 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.
403ip_not_allowedL'IP appelante est hors de la liste blanche configurée sur la clé.Ajoutez votre IP sortante dans les restrictions de la clé API.
404not_foundLe 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.
422validation_errorEn 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_….
429rate_limitedQuota 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.
500internal_errorErreur 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.

Voir aussi

Continuer

Autres tutoriels à suivre