API et SDK de réception

La Réception (intake) vous permet de recevoir des fichiers de tiers en toute sécurité, sans qu'ils aient besoin d'un compte Coffrify. Le principe repose sur deux clés complémentaires : une publishable_key (préfixe cip_) sûre à exposer dans le navigateur pour que vos correspondants déposent leurs fichiers, et votre clé secrète (préfixe cof_) qui reste sur votre serveur pour lister et récupérer les dépôts. Les données sont hébergées en Union européenne. Vous pouvez activer un chiffrement de bout en bout optionnel : la clé reste chez vous et le serveur ne peut pas lire le contenu. Cette page décrit comment créer un point de réception, configurer ses options, intégrer le dépôt côté client et exploiter les dépôts côté serveur.

Avant de commencer

Toutes les requêtes se font sur la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>. La création d'un point de réception nécessite le scope intake:write. La lecture des dépôts côté serveur nécessite le scope intake:read. N'accordez à chaque clé que les scopes strictement nécessaires. Pour vos premiers essais, vous pouvez utiliser une clé de test (cof_test_…) ou une clé bac à sable éphémère (cof_sandbox_…, isolée et valable 24 h) afin de ne pas toucher vos données de production.

Créer un point de réception

Un point de réception se crée côté serveur avec votre clé secrète et le scope intake:write. Le corps accepte un name lisible, ainsi que plusieurs options de configuration : allowed_origins restreint les domaines autorisés à initier un dépôt depuis le navigateur, metadata_policy contrôle les métadonnées que vous souhaitez collecter, et reference_required impose à vos correspondants de fournir une référence lors du dépôt.

curl -X POST https://api.coffrify.com/v1/intakes \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_SECRETE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: intake-rh-2026-06-10" \
  -d '{
    "name": "Dossiers candidats RH",
    "allowed_origins": ["https://recrutement.exemple.fr"],
    "metadata_policy": "minimal",
    "reference_required": true
  }'

La réponse contient l'identifiant du point de réception (id) et la publishable_key. Cette publishable_key n'est affichée qu'une seule fois : conservez-la dans la configuration de votre application front. Si vous la perdez, vous pourrez en générer une nouvelle, mais l'ancienne devra être révoquée.

{
  "id": "intk_8sf2k1d9a0",
  "name": "Dossiers candidats RH",
  "publishable_key": "cip_live_3xQ9aB7cD2eF5gH8jK",
  "allowed_origins": ["https://recrutement.exemple.fr"],
  "metadata_policy": "minimal",
  "reference_required": true,
  "created_at": "2026-06-10T09:24:00Z"
}

Intégrer le dépôt côté navigateur

Côté client, vous utilisez uniquement la publishable_key (cip_…). Elle est conçue pour être exposée dans le navigateur : elle permet de déposer des fichiers vers votre point de réception, mais ne donne aucun accès en lecture aux dépôts existants. Pensez à déclarer l'origine de votre site dans allowed_origins lors de la création pour que les dépôts soient acceptés.

import { CoffrifyIntake } from "@coffrify/intake";
 
const intake = new CoffrifyIntake({
  publishableKey: "cip_live_3xQ9aB7cD2eF5gH8jK",
});
 
const input = document.querySelector("#fichier");
 
input.addEventListener("change", async () => {
  const file = input.files[0];
 
  const result = await intake.upload({
    file,
    reference: "CAND-2026-0481", // requis si reference_required = true
    metadata: { poste: "Développeur back-end" },
  });
 
  console.log("Dépôt envoyé, référence :", result.reference);
});

Lister et récupérer les dépôts côté serveur

Une fois les fichiers déposés, vous les consultez côté serveur avec votre clé secrète (cof_…) et le scope intake:read. L'endpoint /v1/intakes/{id}/documents liste les dépôts reçus pour un point de réception donné, avec leur référence et leurs métadonnées.

curl https://api.coffrify.com/v1/intakes/intk_8sf2k1d9a0/documents \
  -H "Authorization: Bearer cof_live_VOTRE_CLE_SECRETE"

{
  "data": [
    {
      "id": "doc_a1b2c3d4e5",
      "reference": "CAND-2026-0481",
      "filename": "cv-dupont.pdf",
      "size": 184320,
      "mime_type": "application/pdf",
      "metadata": { "poste": "Développeur back-end" },
      "received_at": "2026-06-10T10:02:11Z"
    }
  ],
  "has_more": false
}

Pour récupérer un dépôt précis, interrogez le même endpoint en ciblant son identifiant. Vous obtenez ses métadonnées et un lien de téléchargement temporaire vous permettant d'importer le fichier dans vos systèmes.

$ curl https://api.coffrify.com/v1/intakes/intk_8sf2k1d9a0/documents/doc_a1b2c3d4e5 \
    -H "Authorization: Bearer cof_live_VOTRE_CLE_SECRETE"

Erreurs et limites

Les erreurs suivent un format uniforme {"error":{"code":"…","message":"…","request_id":"…"}}. Les codes les plus courants sont invalid_api_key (clé absente ou invalide), scope_missing (le scope intake:write ou intake:read manque), validation_error (corps mal formé, par exemple une référence manquante alors que reference_required est vrai), not_found et rate_limited. Pensez à toujours consigner le request_id : il accélère le support.

• Surveillez les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy pour anticiper les limites de débit.
• Sur une réponse 429, respectez l'en-tête Retry-After avant de réessayer.
• Réservez la publishable_key (cip_…) au navigateur ; ne l'utilisez jamais pour lire les dépôts.
• Gardez la clé secrète (cof_…) uniquement côté serveur, dans une variable d'environnement.