Référence API REST

L'API REST de Coffrify vous permet de piloter par programme l'intégralité de la plateforme : créer des transferts de fichiers chiffrés, recevoir des documents via la réception sécurisée, gérer des coffres et des collections, configurer des webhooks et interroger l'audit ou les analytics. Toutes les données restent hébergées dans l'Union européenne et le traitement respecte le RGPD. Par défaut, le chiffrement est assuré côté serveur en AES-256-GCM ; un mode chiffrement de bout en bout (zero-knowledge) optionnel garde la clé chez vous, de sorte que le serveur ne lit jamais le contenu. Cette page décrit les conventions transverses de l'API v1, puis dresse le panorama des ressources disponibles.

URL de base et versioning

Toutes les requêtes ciblent la version v1 de l'API, accessible à l'URL de base suivante. Le numéro de version fait partie du chemin : il ne change pas tant que des modifications rétrocompatibles sont publiées, et chaque réponse renvoie l'en-tête X-Coffrify-Api-Version (par exemple 2026-05-14) qui identifie la révision exacte du contrat servie.

https://api.coffrify.com/v1

Les requêtes et les réponses sont en JSON (Content-Type: application/json). Les dates sont au format ISO 8601 en UTC (par exemple 2026-05-14T09:30:00Z). Les montants de durée s'expriment en heures (expires_in_hours) et les tailles de fichier en octets (size). Le CORS est activé, et chaque réponse expose les en-têtes de version, de limitation de débit et de rejeu d'idempotence.

Authentification

Chaque appel s'authentifie par une clé API transmise dans l'en-tête Authorization selon le schéma Bearer. Conservez vos clés secrètes côté serveur : elles ne doivent jamais être exposées dans un navigateur, une application mobile ou un dépôt de code public.

$ curl https://api.coffrify.com/v1/transfers \
    -H "Authorization: Bearer cof_live_votre_cle_secrete"

Le préfixe de la clé indique son environnement et sa nature. Les environnements sont isolés : une clé sandbox ne voit que les ressources sandbox, et une clé live ne voit jamais le sandbox.

Scopes et permissions

Chaque clé porte un ensemble de scopes qui délimitent précisément ce qu'elle peut faire. Accordez le minimum nécessaire : une intégration qui ne fait qu'envoyer des fichiers n'a besoin que de transfers:write. Les scopes suivent la forme ressource:action.

Certaines ressources de niveau workspace (coffres, recipients, audit, analytics) utilisent leurs propres scopes dédiés. Reportez-vous à la documentation de chaque ressource pour la liste exacte ; la page des scopes de votre espace recense l'ensemble des scopes disponibles.

Pagination par curseur

Les points de terminaison de type liste renvoient une enveloppe uniforme et paginent par curseur, ce qui reste stable même lorsque de nouvelles ressources sont créées entre deux appels. Utilisez limit pour fixer la taille de page (jusqu'à 100) et cursor pour récupérer la page suivante. La réponse contient object: "list", le tableau data, le booléen has_more et, lorsqu'il reste des éléments, next_cursor à repasser tel quel dans le paramètre cursor.

# Première page
curl "https://api.coffrify.com/v1/transfers?limit=50" \
  -H "Authorization: Bearer cof_live_votre_cle"
 
# Page suivante : on repasse next_cursor
curl "https://api.coffrify.com/v1/transfers?limit=50&cursor=eyJ0cyI6..." \
  -H "Authorization: Bearer cof_live_votre_cle"

Tant que has_more vaut true, répétez l'appel avec le next_cursor reçu ; arrêtez-vous lorsque has_more vaut false et que next_cursor est null. Le curseur étant opaque, ne cherchez pas à l'interpréter ni à le construire vous-même.

Idempotence

Pour fiabiliser les écritures malgré les coupures réseau, transmettez un en-tête Idempotency-Key (de 8 à 255 caractères, par exemple un UUID) sur vos requêtes POST, PUT, PATCH et DELETE. Si vous rejouez la même clé avec un corps identique, l'API renvoie la réponse mémorisée au lieu de réexécuter l'action, et ajoute l'en-tête X-Coffrify-Idempotent-Replay: true. Rejouer la même clé avec un corps différent renvoie une erreur 409 (idempotency_conflict).

$ curl -X POST https://api.coffrify.com/v1/transfers \
    -H "Authorization: Bearer cof_live_votre_cle" \
    -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
    -H "Content-Type: application/json" \
    -d '{"files":[{"name":"contrat.pdf","size":248913,"mime_type":"application/pdf"}]}'

Limitation de débit

L'API applique une limite de débit par espace de travail. Chaque réponse expose X-RateLimit-Limit (plafond sur la fenêtre), X-RateLimit-Remaining (appels restants), X-RateLimit-Reset (date Unix de réinitialisation) et X-RateLimit-Policy. Lorsque la limite est atteinte, l'API répond 429 avec le code rate_limited et l'en-tête Retry-After qui indique le nombre de secondes à attendre avant de réessayer. Prévoyez une logique de nouvelle tentative avec repli exponentiel qui respecte cet en-tête.

Structure des erreurs

Les réponses d'erreur utilisent les codes HTTP standards (4xx pour les erreurs côté client, 5xx côté serveur) et un corps JSON uniforme. L'objet error contient un code lisible par machine, un message explicatif et un request_id à fournir au support pour tracer l'appel.

{
  "error": {
    "code": "validation_error",
    "message": "files[] required",
    "request_id": "req_8f2c1a9b4e"
  }
}

Panorama des ressources

L'API v1 expose les familles de ressources suivantes. Chacune dispose de sa propre page détaillée décrivant les champs, les corps de requête et les codes de réponse.

• Transferts (/v1/transfers) : créer, lister, consulter et supprimer des transferts de fichiers ; obtenir les URL de téléversement présignées.
• Réception sécurisée (/v1/intakes) : créer des points de réception, obtenir une clé publishable cip_ pour le navigateur et lister les documents reçus.
• Coffres (/v1/coffres) : data rooms avec fichiers, dossiers, invités, filigrane, NDA et export.
• Collections (/v1/collections) : regrouper et organiser des transferts sous une URL partagée.
• Webhooks (/v1/webhooks) : s'abonner aux événements (transfer.*, coffre.*, request.* et autres) et recevoir des notifications signées.
• Clés API (/v1/api-keys) : créer, lister et révoquer des clés par programme.
• Recipients (/v1/recipients) : carnet d'adresses des destinataires.
• Audit (/v1/audit) : journal horodaté des actions de l'espace de travail.
• Analytics (/v1/analytics) : statistiques d'usage, dont /geo, /funnel, /heatmap, /top-transfers et /top-recipients.
• RGPD (/v1/gdpr/export) : déclencher un export des données de l'espace.

Pour démarrer, créez une clé API depuis votre espace Coffrify, choisissez les scopes adaptés à votre cas d'usage, puis appelez POST /v1/transfers. Les pages dédiées à chaque ressource détaillent ensuite les paramètres et les réponses, et vous pouvez automatiser l'ensemble avec la CLI cof ou le SDK JavaScript et TypeScript, qui partagent exactement ces points de terminaison et ces clés.