Créer une drop-box publique pour recevoir des fichiers anonymes

Apprenez à déclarer une drop-box via l'interface Coffrify, à générer un token `cit_live_…`, puis à soumettre un dépôt côté serveur avec l'endpoint POST /v1/inbox/submit.

Télécharger en PDF

Une drop-box Coffrify est un point de collecte public qui vous permet de recevoir des fichiers de la part d'expéditeurs anonymes (clients, partenaires, auditeurs) sans leur demander de compte. L'endpoint POST /v1/inbox/submit est conçu pour les intégrations côté serveur : votre backend soumet les métadonnées d'un dépôt (email de l'expéditeur, message facultatif, liste des fichiers) en échange d'un submission_id et, si la box l'autorise, d'un tracking_token que vous pouvez remettre à l'expéditeur pour suivre l'état de son envoi. Les uploads binaires restent gérés par un flow presigné distinct ; cet endpoint valide et enregistre la notification de dépôt.

POST/v1/inbox/submitCrée une notification de dépôt dans la drop-box liée au token fourni. Retourne un submission_id et, si le suivi est activé, un tracking_token.

Authentification

Cet endpoint utilise un token de drop-box au format cit_live_…, distinct de vos clés d'API workspace (cof_live_…). Ce token est généré depuis l'interface Coffrify dans Paramètres > Drop-boxes > Tokens. Il doit avoir le scope read_write : un token read_only est rejeté avec une erreur scope_missing (HTTP 403). Transmettez-le dans l'en-tête Authorization : Bearer cit_live_….

Corps de la requête

Le dépôt déclare le ou les fichiers à recevoir et, en option, des métadonnées sur l'expéditeur. Le tableau ci-dessous liste les champs acceptés.

Champ	Type	Requis	Description
requester_email	string	Oui	Adresse email de l'expéditeur (max 254 caractères, format validé). Rejetée si absente ou invalide.
requester_name	string	Conditionnel	Nom de l'expéditeur (max 80 caractères). Obligatoire si la drop-box a `require_requester_name` activé.
message	string	Non	Message libre accompagnant le dépôt. Ignoré si la box a `allow_message` désactivé. Tronqué à `message_max_chars` (défaut 500).
files	array	Non	Liste des métadonnées de fichiers à déclarer. Chaque élément contient `name` (string) et `size` (number, en octets). Maximum 50 fichiers (ou le plafond configuré sur la box).

Exemple d'appel

L'exemple ci-dessous soumet un dépôt à une drop-box via son token. À exécuter côté serveur. Choisissez votre langage.

curl -X POST https://api.coffrify.com/v1/inbox/submit \
  -H "Authorization: Bearer cit_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "requester_email": "alice@example.com",
    "requester_name": "Alice Martin",
    "message": "Voici les documents demandés pour l'audit Q2.",
    "files": [
      { "name": "bilan-2025.pdf", "size": 204800 },
      { "name": "annexes.zip", "size": 1048576 }
    ]
  }'

Réponse

{
  "ok": true,
  "submission_id": "sub_01hwxxxxxxxxxxxxxx",
  "tracking_token": "aB3kR7mNqPsT2uVwXyZ0",
  "tracking_expires_at": "2026-07-06T14:32:00.000Z"
}

En cas de succès, l'endpoint retourne HTTP 201. Si la drop-box a allow_requester_tracking désactivé, tracking_token et tracking_expires_at sont null. Le tracking_token est un jeton opaque base64url de 24 caractères : conservez-le pour interroger l'état du dépôt ultérieurement. La durée de validité est configurable sur la box (défaut : 30 jours).

Erreurs

Les erreurs portent surtout sur un token de drop-box invalide ou expiré, ou un dépôt malformé. Le tableau ci-dessous indique la résolution.

Code HTTP	error	Quand	Résolution
401	invalid_token	Le header `Authorization` est absent, mal formé, ou ne commence pas par `cit_live_`.	Vérifiez le token dans Coffrify > Drop-boxes > Tokens. Assurez-vous d'utiliser le préfixe `cit_live_…`.
401	invalid_token	Le token est inconnu en base ou a été révoqué (`revoked_at` non null).	Générez un nouveau token depuis l'interface.
403	scope_missing	Le token a le scope `read_only` ; l'endpoint exige `read_write`.	Créez un nouveau token avec le scope `read_write`.
400	invalid_email	`requester_email` est absent, mal formé ou dépasse 254 caractères.	Transmettez une adresse email valide dans le champ `requester_email`.
400	name_required	La drop-box requiert un nom (`require_requester_name` = true) mais `requester_name` est vide.	Ajoutez le champ `requester_name` dans le corps de la requête.
400	too_many_files	Le tableau `files` dépasse la limite configurée sur la box (max absolu : 50).	Réduisez le nombre de fichiers ou faites plusieurs soumissions.
402	uploads_blocked	Le workspace est bloqué pour cause de dépassement de quota, facture impayée, suspension manuelle ou vérification de conformité.	Consultez `resolve_url` dans le corps de l'erreur (https://billing.coffrify.com ou https://help.coffrify.com).
410	box_disabled	La drop-box cible est désactivée ou introuvable.	Vérifiez que la box est active dans Coffrify > Drop-boxes.
500	insert_failed	Erreur interne lors de l'insertion en base.	Réessayez. Si l'erreur persiste, contactez le support Coffrify.

Voir aussi

Référence complète POST /v1/inbox/submit
Suivre l'état d'un dépôt avec le tracking_token
Générer des URLs presignées pour l'upload binaire
Configurer les quotas et le blocage d'uploads
Gérer les tokens de drop-box (création, révocation)

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→