L'Inbox Coffrify repose sur deux objets complémentaires : les drop-boxes (canal libre, toujours ouvert) et les requests (demandes ciblées avec expiration et quota de soumissions). Ce guide vous montre comment soumettre des métadonnées de fichiers dans une drop-box via POST /v1/inbox/submit, comment écouter les événements request.submitted et request.completed via un webhook, et comment mettre à jour le statut d'une demande après traitement avec PATCH /v1/requests/{id}.
/v1/inbox/submitCrée une soumission dans la drop-box liée au token `cit_live_`. Accepte les métadonnées de fichiers (nom, taille), l'e-mail et le message de l'expéditeur. Retourne un `submission_id` et un `tracking_token` si le tracking est activé sur la box./v1/requests/{id}Récupère une demande de fichiers et ses statistiques de soumissions (pending, reviewed, approved, rejected, spam). Scope requis : `transfers:read`.PATCH/v1/requests/{id}Met à jour les champs d'une demande : titre, description, statut, notifications, expiration, quota, taille max de fichier, emoji et couleur. Scope requis : `transfers:write`.Authentification
Le endpoint POST /v1/inbox/submit utilise un token de drop-box au format cit_live_… passé en Authorization: Bearer cit_live_…. Ce token est lié à une drop-box unique et doit avoir le scope read_write. Les endpoints GET et PATCH /v1/requests/{id} utilisent une clé API standard (cof_live_… ou cof_test_…) avec les scopes transfers:read et transfers:write respectivement.
Corps de la requête
Le corps varie selon l'endpoint (soumission ou mise à jour de demande). Le tableau ci-dessous détaille, pour chacun, les champs acceptés.
| Endpoint | Champ | Type | Requis | Description |
|---|---|---|---|---|
POST /v1/inbox/submit | requester_email | string | Oui | E-mail de l'expéditeur (max 254 car., RFC 5322). |
POST /v1/inbox/submit | requester_name | string | Conditionnel | Nom de l'expéditeur (max 80 car.). Obligatoire si la box a require_requester_name = true. |
POST /v1/inbox/submit | files | array | Non | Tableau de { name, size }. Max 50 entrées. size en octets. |
POST /v1/inbox/submit | message | string | Non | Message libre joint à la soumission. Ignoré si allow_message = false. Tronqué à message_max_chars (défaut 500). |
PATCH /v1/requests/{id} | status | string | Non | active, paused, expired ou archived. |
PATCH /v1/requests/{id} | title | string | Non | Titre de la demande (max 200 car.). |
PATCH /v1/requests/{id} | notify_email | string|null | Non | E-mail de notification à chaque soumission. |
PATCH /v1/requests/{id} | expires_at | string|null | Non | Date d'expiration ISO 8601. null supprime la limite. |
PATCH /v1/requests/{id} | max_submissions | integer|null | Non | Quota total de soumissions. null = illimité. |
PATCH /v1/requests/{id} | max_file_size_mb | integer | Non | Taille max par fichier en Mo. Valeurs : 100, 500, 1000 ou 2000. |
Les exemples ci-dessous soumettent un dépôt, puis reçoivent l'événement côté serveur. Choisissez votre langage.
Réponse et routage Webhook
La soumission renvoie un submission_id et déclenche un événement webhook côté serveur. L'exemple ci-dessous montre un récepteur qui vérifie la signature, puis route le fichier reçu.
Erreurs
Les erreurs portent sur un token de drop-box invalide, une demande introuvable ou un corps malformé. Le tableau ci-dessous indique la résolution.
| Code HTTP | Code erreur | Quand | Resolution |
|---|---|---|---|
| 401 | invalid_token | Token cit_live_… absent, malformé ou révoqué. | Vérifiez le token de drop-box dans le tableau de bord et passez-le en Authorization: Bearer cit_live_…. |
| 403 | scope_missing | Le token a un scope read_only. | Générez un token avec le scope read_write sur la drop-box. |
| 400 | invalid_email | requester_email absent ou format invalide. | Fournissez une adresse e-mail valide de moins de 254 caractères. |
| 400 | name_required | La box exige 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 le quota de la drop-box (max absolu : 50). | Réduisez le nombre de fichiers ou scindez la soumission. |
| 400 | validation_error | Champ invalide ou aucun champ modifiable envoyé à PATCH /v1/requests/{id}. | Consultez la table des champs et envoyez au moins un champ valide. |
| 402 | uploads_blocked | Cap mensuel atteint, facture impayée (payment_past_due), blocage manuel ou révision fraude. | Consultez reason et resolve_url dans la réponse. Réglez la situation via billing.coffrify.com ou help.coffrify.com. |
| 404 | not_found | L'identifiant de demande {id} n'existe pas ou n'appartient pas au workspace. | Vérifiez l'identifiant via GET /v1/requests. |
| 410 | box_disabled | La drop-box ciblée par le token est désactivée. | Réactivez la drop-box dans les paramètres ou utilisez un token lié à une box active. |
| 429 | rate_limited | La limite de requêtes par minute est dépassée. | Respectez l'en-tête Retry-After retourné dans la réponse. |
| 500 | internal_error | Erreur interne Coffrify. | Réessayez après quelques secondes et transmettez le X-Request-Id au support si l'erreur persiste. |
- Créer une demande de fichiers (Request)
- Configurer et tester un webhook
- Catalogue d'événements webhook
- Référence : POST /v1/inbox/submit
- Référence : PATCH /v1/requests/{id}
- Gestion des erreurs API Coffrify