Recevoir des fichiers : les demandes

Créez une page de dépôt publique, recevez des soumissions et gérez leur cycle de vie complet depuis l'API Coffrify.

Une demande (ou request) est une page de dépôt publique que vous publiez à vos contacts, clients ou partenaires afin qu'ils vous envoient des fichiers sans créer de compte Coffrify. Chaque demande dispose d'un short_code unique (par exemple ax7k3m2r) qui compose son URL publique. Dès qu'un expéditeur dépose des fichiers, une soumission est créée et associée à la demande. Vous pouvez alors consulter, filtrer et qualifier chaque soumission (statuts pending, reviewed, approved, rejected, spam) directement depuis l'API ou l'interface.

Endpoints concernés

GET/v1/requestsLister toutes les demandes du workspace (max 200, triées par date de création décroissante).POST/v1/requestsCréer une nouvelle demande de fichiers.GET/v1/requests/{id}Récupérer une demande par son identifiant, avec les statistiques de soumissions ventilées par statut.PATCH/v1/requests/{id}Mettre à jour les champs modifiables d'une demande existante.DELETE/v1/requests/{id}Supprimer définitivement une demande (et émettre l'événement request.deleted).GET/v1/requests/{id}/submissionsLister les soumissions reçues pour une demande, avec filtre optionnel par statut.PATCH/v1/requests/{id}/submissionsMettre à jour le statut d'une soumission (qualification manuelle ou automatisée).

Authentification

Tous ces endpoints nécessitent une clé API au format cof_live_… (ou cof_test_… en sandbox) transmise dans l'en-tête Authorization: Bearer. Le scope requis est transfers:write pour les opérations d'écriture (POST, PATCH, DELETE) et pour la lecture (GET). Aucun des endpoints ci-dessus n'est public : l'accès sans clé valide retourne 401 unauthorized.

Créer une demande

Envoyez un POST /v1/requests avec au minimum le champ title. Les champs optionnels permettent de restreindre les dépôts, de définir des limites de taille, d'ajouter une notification par e-mail ou Slack Webhook et de personnaliser l'apparence de la page publique.

Corps de la requête

Champ	Type	Requis	Description
title	string (max 200)	Oui	Titre affiché sur la page publique de dépôt.
description	string (max 2000)	Non	Texte d'instructions visible par l'expéditeur.
is_password_protected	boolean	Non	Si `true`, le champ `password` devient obligatoire.
password	string	Conditionnel	Mot de passe haché en SHA-256 côté serveur. Obligatoire si `is_password_protected: true`.
allowed_emails	string[]	Non	Liste blanche d'adresses e-mail autorisées à soumettre.
expires_at	string (ISO 8601)	Non	Date d'expiration de la demande. Après cette date, les dépôts sont refusés.
max_submissions	integer > 0	Non	Nombre maximum de soumissions acceptées avant fermeture automatique.
max_file_size_mb	integer	Non	Taille maximale par fichier. Valeurs autorisées : `100`, `500`, `1000`, `2000`.
max_files_per_submission	integer (1-100)	Non	Nombre maximal de fichiers par soumission.
notify_email	string	Non	Adresse e-mail notifiée à chaque nouvelle soumission.
notify_slack_webhook	string	Non	URL de Webhook Slack notifiée à chaque nouvelle soumission.
cover_emoji	string (max 8)	Non	Emoji affiché en couverture de la page publique.
cover_color	string (#rrggbb)	Non	Couleur de fond de la page publique (format hexadécimal strict, ex. `#1a73e8`).

Exemples d'appel

curl -X POST https://api.coffrify.com/v1/requests \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Documents RH - Recrutement 2026",
    "description": "Merci de déposer votre CV et vos justificatifs dans ce formulaire sécurisé.",
    "max_file_size_mb": 100,
    "max_files_per_submission": 5,
    "expires_at": "2026-09-30T23:59:59Z",
    "notify_email": "rh@exemple.fr",
    "cover_emoji": "📋",
    "cover_color": "#1a73e8"
  }'

Réponse : création réussie (201)

{
  "id": "req_01j9z7xt4b3kfc82n6p0qxmvhd",
  "short_code": "ax7k3m2r",
  "title": "Documents RH - Recrutement 2026",
  "description": "Merci de déposer votre CV et vos justificatifs dans ce formulaire sécurisé.",
  "is_password_protected": false,
  "allowed_emails": null,
  "status": "active",
  "expires_at": "2026-09-30T23:59:59.000Z",
  "max_submissions": null,
  "total_submissions": 0,
  "allowed_file_types": null,
  "max_file_size_mb": 100,
  "max_files_per_submission": 5,
  "notify_email": "rh@exemple.fr",
  "cover_emoji": "📋",
  "cover_color": "#1a73e8",
  "created_at": "2026-06-06T09:12:44.312Z",
  "updated_at": "2026-06-06T09:12:44.312Z"
}

La page publique de dépôt est immédiatement accessible à l'adresse https://app.coffrify.com/r/{short_code}. Partagez ce lien avec vos expéditeurs : aucune inscription ni clé API n'est requise de leur côté.

Lire une demande et ses statistiques

Un GET /v1/requests/{id} retourne la demande enrichie d'un objet submission_stats qui ventile le nombre de soumissions par statut (pending, reviewed, approved, rejected, spam). Cela évite de lister toutes les soumissions pour obtenir un tableau de bord synthétique.

{
  "id": "req_01j9z7xt4b3kfc82n6p0qxmvhd",
  "short_code": "ax7k3m2r",
  "title": "Documents RH - Recrutement 2026",
  "status": "active",
  "total_submissions": 12,
  "submission_stats": {
    "pending": 5,
    "reviewed": 4,
    "approved": 2,
    "rejected": 1,
    "spam": 0
  },
  "expires_at": "2026-09-30T23:59:59.000Z",
  "max_submissions": null,
  "max_file_size_mb": 100,
  "max_files_per_submission": 5,
  "notify_email": "rh@exemple.fr",
  "cover_emoji": "📋",
  "cover_color": "#1a73e8",
  "created_at": "2026-06-06T09:12:44.312Z",
  "updated_at": "2026-06-06T09:14:00.000Z"
}

Gérer le cycle de vie d'une demande

Le champ status contrôle la disponibilité publique de la demande. Utilisez PATCH /v1/requests/{id} pour le faire évoluer. Les quatre valeurs acceptées sont : active (dépôts autorisés), paused (page désactivée temporairement), expired (plus de nouveaux dépôts) et archived (demande archivée, non visible).

$ curl -X PATCH https://api.coffrify.com/v1/requests/req_01j9z7xt4b3kfc82n6p0qxmvhd \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Lister et qualifier les soumissions

Chaque soumission contient les champs submitter_name, submitter_email, note, total_files, total_size_bytes, transfer_id (identifiant du transfert chiffré généré lors du dépôt) et status. Filtrez par statut avec le paramètre de requête ?status=pending (valeurs : pending, reviewed, approved, rejected, spam). Le paramètre limit accepte une valeur entre 1 et 500 (défaut : 200).

# Lister les soumissions en attente
curl https://api.coffrify.com/v1/requests/req_01j9z7xt4b3kfc82n6p0qxmvhd/submissions?status=pending \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# Qualifier une soumission comme approuvée
curl -X PATCH https://api.coffrify.com/v1/requests/req_01j9z7xt4b3kfc82n6p0qxmvhd/submissions \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "submission_id": "sub_01j9z8aa1c4kfc82n6p0qxmvhd",
    "status": "approved"
  }'

Réponse : liste de soumissions

{
  "object": "list",
  "request_id": "req_01j9z7xt4b3kfc82n6p0qxmvhd",
  "data": [
    {
      "id": "sub_01j9z8aa1c4kfc82n6p0qxmvhd",
      "request_id": "req_01j9z7xt4b3kfc82n6p0qxmvhd",
      "workspace_id": "ws_01j7abc",
      "submitter_name": "Marie Dupont",
      "submitter_email": "marie.dupont@exemple.fr",
      "submitter_ip": "92.184.12.5",
      "submitter_country": "FR",
      "note": "Voici mon dossier complet comme demandé.",
      "status": "pending",
      "transfer_id": "tr_01j9z8bb9c5kfd82n6p1qymwhd",
      "total_files": 3,
      "total_size_bytes": 4587520,
      "submitted_at": "2026-06-06T10:05:22.000Z",
      "reviewed_at": null,
      "reviewed_by": null
    }
  ]
}

Chiffrement de bout en bout des soumissions

Depuis la Phase 4 E2E, le endpoint public de dépôt (/v1/public/request-submit) accepte un champ encryption_mode: "e2e_v1". Lorsqu'il est activé, les fichiers sont chiffrés par le navigateur de l'expéditeur avec AES-256-GCM avant tout envoi réseau. La clé ne quitte jamais le client : elle est transmise uniquement dans le fragment d'URL (#key=…), invisible des journaux serveur. Le champ encryption_metadata stocke les informations de vecteur d'initialisation (IV) par fichier, sans jamais contenir la clé brute (les valeurs key, raw_key, secret ou password sont rejetées avec 400).

Erreurs

Code HTTP	Code d'erreur	Quand	Résolution
400	validation_error	`title` absent ou vide à la création.	Fournir un `title` non vide (max 200 caractères).
400	validation_error	`is_password_protected: true` sans `password`.	Inclure le champ `password` dans le corps.
400	validation_error	`max_file_size_mb` hors des valeurs autorisées.	Utiliser exclusivement 100, 500, 1000 ou 2000.
400	validation_error	`max_files_per_submission` hors de la plage 1-100.	Passer une valeur entière entre 1 et 100.
400	validation_error	`status` invalide dans PATCH.	Valeurs autorisées : `active`, `paused`, `expired`, `archived`.
400	validation_error	Corps PATCH sans aucun champ valide.	Vérifier les noms des champs envoyés.
400	validation_error	`status` de soumission invalide dans PATCH submissions.	Valeurs autorisées : `pending`, `reviewed`, `approved`, `rejected`, `spam`.
401	unauthorized	Clé API absente ou malformée.	Transmettre `Authorization: Bearer cof_live_…` ou `cof_test_…`.
403	forbidden	Scope `transfers:write` manquant.	Régénérer la clé avec le scope requis dans les paramètres du workspace.
404	not_found	Identifiant de demande ou de soumission inexistant dans ce workspace.	Vérifier l'`id` et le workspace utilisé.
500	internal_error	Erreur base de données inattendue.	Réessayer après quelques secondes. Contacter le support si l'erreur persiste.

Voir aussi

Envoyer des fichiers : les transferts
Authentification et clés API
Recevoir des événements : les Webhooks
Chiffrement de bout en bout
Référence complète de l'API Requests

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→