⚙️
Inbox & demandes de fichiers·Intermédiaire·10 min

Traiter et router automatiquement les fichiers reçus dans l'Inbox

Apprenez à soumettre des fichiers dans une drop-box via l'API, à surveiller les soumissions avec des webhooks et à mettre à jour le statut d'une demande de fichiers de façon programmatique.

Télécharger en PDF

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}.

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

EndpointChampTypeRequisDescription
POST /v1/inbox/submitrequester_emailstringOuiE-mail de l'expéditeur (max 254 car., RFC 5322).
POST /v1/inbox/submitrequester_namestringConditionnelNom de l'expéditeur (max 80 car.). Obligatoire si la box a require_requester_name = true.
POST /v1/inbox/submitfilesarrayNonTableau de { name, size }. Max 50 entrées. size en octets.
POST /v1/inbox/submitmessagestringNonMessage libre joint à la soumission. Ignoré si allow_message = false. Tronqué à message_max_chars (défaut 500).
PATCH /v1/requests/{id}statusstringNonactive, paused, expired ou archived.
PATCH /v1/requests/{id}titlestringNonTitre de la demande (max 200 car.).
PATCH /v1/requests/{id}notify_emailstring|nullNonE-mail de notification à chaque soumission.
PATCH /v1/requests/{id}expires_atstring|nullNonDate d'expiration ISO 8601. null supprime la limite.
PATCH /v1/requests/{id}max_submissionsinteger|nullNonQuota total de soumissions. null = illimité.
PATCH /v1/requests/{id}max_file_size_mbintegerNonTaille 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.

# 1. Soumettre des fichiers dans une drop-box
curl -X POST https://api.coffrify.com/v1/inbox/submit \
-H "Authorization: Bearer cit_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"requester_email": "alice@exemple.fr",
"requester_name": "Alice Martin",
"message": "Voici les documents demandes.",
"files": [
{ "name": "contrat.pdf", "size": 204800 },
{ "name": "annexe.xlsx", "size": 51200 }
]
}'
 
# 2. Mettre la demande en pause apres traitement
curl -X PATCH https://api.coffrify.com/v1/requests/req_abc123 \
-H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'

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.

// POST /v1/inbox/submit, 201 Created
{
"ok": true,
"submission_id": "7f3a1c2d-e4b5-4f8a-9c0d-1e2f3a4b5c6d",
"tracking_token": "aB3xZ9mKpQ2nWv5tYr8s",
"tracking_expires_at": "2026-07-06T14:23:00.000Z"
}
 
// PATCH /v1/requests/{id}, 200 OK
{
"id": "req_abc123",
"short_code": "m4k9pz2q",
"title": "Documents comptables T2 2026",
"is_password_protected": false,
"allowed_emails": ["alice@exemple.fr"],
"status": "archived",
"expires_at": "2026-06-30T23:59:59.000Z",
"max_submissions": 10,
"total_submissions": 7,
"notify_email": "comptable@cabinet.fr",
"cover_color": "#4F46E5",
"cover_emoji": "\ud83d\udcc1",
"updated_at": "2026-06-06T09:15:00.000Z"
}
 
// GET /v1/requests/{id}, statistiques de soumissions incluses
{
"id": "req_abc123",
"submission_stats": {
"pending": 3,
"reviewed": 2,
"approved": 1,
"rejected": 1,
"spam": 0
}
}
# Recepteur webhook Flask, router les fichiers recus
import hashlib
import hmac
from flask import Flask, request, abort
 
app = Flask(__name__)
WEBHOOK_SECRET = "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
def verify_signature(payload: bytes, header: str | None) -> bool:
if not header:
return False
sig = header.removeprefix("sha256=")
expected = hmac.new(
WEBHOOK_SECRET.encode(),
payload,
hashlib.sha256).hexdigest()
return hmac.compare_digest(sig, expected)
 
@app.post("/webhook/coffrify")
def coffrify_webhook():
raw = request.get_data()
sig = request.headers.get("X-Coffrify-Signature")
if not verify_signature(raw, sig):
abort(401, "Signature invalide")
 
event = request.get_json()
event_type = event.get("type")
 
if event_type == "request.submitted":
request_id = event["payload"].get("request_id")
print(f"Nouvelle soumission sur la demande {request_id}")
# Exemple : lancer un pipeline de traitement
# pipeline.process(request_id, event["payload"])
 
elif event_type == "request.completed":
print(f"Demande {event['payload'].get('request_id')} completee.")
 
return {"received": True}, 200

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 HTTPCode erreurQuandResolution
401invalid_tokenToken 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_….
403scope_missingLe token a un scope read_only.Générez un token avec le scope read_write sur la drop-box.
400invalid_emailrequester_email absent ou format invalide.Fournissez une adresse e-mail valide de moins de 254 caractères.
400name_requiredLa box exige require_requester_name = true mais requester_name est vide.Ajoutez le champ requester_name dans le corps de la requête.
400too_many_filesLe tableau files dépasse le quota de la drop-box (max absolu : 50).Réduisez le nombre de fichiers ou scindez la soumission.
400validation_errorChamp invalide ou aucun champ modifiable envoyé à PATCH /v1/requests/{id}.Consultez la table des champs et envoyez au moins un champ valide.
402uploads_blockedCap 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.
404not_foundL'identifiant de demande {id} n'existe pas ou n'appartient pas au workspace.Vérifiez l'identifiant via GET /v1/requests.
410box_disabledLa 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.
429rate_limitedLa limite de requêtes par minute est dépassée.Respectez l'en-tête Retry-After retourné dans la réponse.
500internal_errorErreur interne Coffrify.Réessayez après quelques secondes et transmettez le X-Request-Id au support si l'erreur persiste.
Continuer

Autres tutoriels à suivre