Environnements : test, live et sandbox

L'API Coffrify expose trois environnements : test, live et sandbox. Vous n'avez aucun en-tête spécial à envoyer ni aucune URL différente à appeler : l'environnement est déterminé par le préfixe de la clé que vous présentez dans Authorization: Bearer. La même requête, envoyée vers https://api.coffrify.com/v1, sera traitée en test, en live ou dans le bac à sable selon que votre clé commence par cof_test_, cof_live_ ou cof_sandbox_. Cette page explique ce que chaque environnement garantit, comment basculer de l'un à l'autre et quelles bonnes pratiques adopter.

Les trois préfixes

Le préfixe se lit au premier coup d'oeil et porte à lui seul le choix de l'environnement. Les clés restreintes (cof_rk_) et les jetons MCP (cof_mcp_) suivent la même convention en insérant l'environnement après leur segment : cof_rk_live_…, cof_mcp_sandbox_…, etc.

Live et test

L'environnement live est la production : chaque transfert créé est réel, partageable et comptabilisé dans votre facturation. L'environnement test offre la même fidélité technique (vraies URL de téléversement, vrai téléchargement, mêmes formats de réponse) mais reste séparé de vos données de production, ce qui en fait l'endroit idéal pour câbler votre intégration, vos webhooks et vos tests automatisés avant de passer en live.

Le bac à sable (sandbox)

Le sandbox est un environnement jetable conçu pour découvrir l'API sans aucune conséquence. Il se distingue par trois propriétés : il est isolé, éphémère et plafonné par des garde-fous. Tout ce qu'une clé sandbox crée vit dans une bulle séparée, disparaît après 24 heures et reste hors facturation.

Isolation

Une clé cof_sandbox_ ne voit que des données sandbox, et une clé cof_live_ ou cof_test_ ne voit jamais le sandbox. Par exemple, un GET /v1/transfers présenté avec une clé sandbox ne renverra que les transferts créés en sandbox ; la même requête avec une clé live ignorera complètement ces transferts. Vous pouvez donc expérimenter librement sans polluer vos listes réelles.

Éphémère (24 heures)

Une session sandbox émet une clé cof_sandbox_ qui expire au bout de 24 heures. Toutes les ressources créées avec cette clé (transferts, fichiers, journaux de requêtes) sont automatiquement purgées après 24 heures, y compris les fichiers stockés. Ne construisez donc rien de durable sur le sandbox : c'est un brouillon, pas un stockage.

Garde-fous

Pour empêcher le sandbox de servir de service de transfert gratuit, des plafonds s'appliquent à la création de transferts. Ils sont propres au sandbox : test et live n'en ont pas.

Le plafond de téléchargements n'échoue pas : si vous demandez max_downloads au-delà de 5 (ou que vous l'omettez), il est ramené à 5. En revanche, dépasser la taille de fichier, le nombre de fichiers ou le quota de 25 transferts sur 24 heures renvoie une erreur explicite.

Hors facturation

Les ressources créées en sandbox ne sont jamais facturées et ne comptent pas dans vos quotas de production. Vous pouvez itérer autant que les garde-fous le permettent sans impact sur votre abonnement.

Comment basculer d'un environnement à l'autre

Basculer revient simplement à changer de clé. Conservez vos clés dans des variables d'environnement distinctes et choisissez la bonne selon le contexte (CI, préproduction, production).

# Test
curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_test_xxx"
 
# Live
curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_xxx"
 
# Sandbox
curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_sandbox_xxx"

Bonnes pratiques

• Stockez chaque clé dans une variable d'environnement dédiée (COFFRIFY_LIVE_KEY, COFFRIFY_TEST_KEY) et ne codez jamais une clé en dur.
• Réservez cof_live_ à la production ; tout le reste (tests, démonstrations, exemples de code) passe par cof_test_ ou cof_sandbox_.
• Utilisez le sandbox pour vos tout premiers appels et vos explorations rapides, le test pour valider une intégration complète et reproductible.
• Ne construisez aucun flux durable sur le sandbox : il est plafonné et purgé après 24 heures.
• Vérifiez le préfixe de la clé avant un déploiement : une clé cof_test_ partie en production ne créera jamais de vrais transferts, et inversement.
• Côté navigateur, n'exposez jamais une clé secrète : pour la réception côté client, utilisez la clé publiable cip_ prévue à cet effet.