Idempotence : éviter les doublons avec Idempotency-Key

Chaque fois que vous envoyez un POST vers l'API Coffrify, un réseau instable peut interrompre la connexion avant que vous receviez la réponse. Sans mécanisme de protection, relancer la requête crée un second transfert ou une seconde boîte de dépôt. L'en-tête Idempotency-Key résout ce problème : si vous renvoyez exactement le même corps avec la même clé, l'API vous restitue la réponse originale sans exécuter l'opération une deuxième fois.

Authentification

Tous les appels mutatifs requièrent une clé API avec le scope transfers:write. Passez votre clé dans l'en-tête Authorization: Bearer <clé>. Le format des clés est cof_live_… en production, cof_test_… en test, et cof_sandbox_… en sandbox. L'idempotence est isolée par workspace et par clé API : deux workspaces différents peuvent réutiliser les mêmes valeurs d'Idempotency-Key sans interférence.

Comment fonctionne l'Idempotency-Key

Lors du premier appel, l'API stocke un verrou associant votre clé, votre workspace, votre clé API et un hash SHA-256 du corps de la requête. La réponse (statut, corps, en-têtes) est persistée à l'issue du traitement. Lors d'un second appel avec la même clé : si le corps est identique, la réponse stockée est retournée immédiatement avec l'en-tête X-Coffrify-Idempotent-Replay: true. Si le corps diffère, l'API répond 409 idempotency_conflict pour vous alerter d'un conflit de paramètres.

Exemple : créer un transfert de façon idempotente

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "files": [{"name": "contrat.pdf", "size": 204800, "mime_type": "application/pdf"}],
    "transfer_title": "Contrat signé",
    "expires_in_hours": 72,
    "max_downloads": 3
  }'

Réponse

Que la réponse soit originale ou rejouée, le corps est identique. Seul l'en-tête X-Coffrify-Idempotent-Replay: true distingue un replay. Le statut HTTP retourné est 201 Created dans les deux cas.

HTTP/1.1 201 Created
X-Request-Id: req_01hwz8k3p2xnvm
X-Coffrify-Api-Version: 2026-05-14
X-Coffrify-Idempotent-Replay: true
 
{
  "transfer": {
    "id": "b2f6e1a0-3c4d-4e5f-9a8b-7c6d5e4f3210",
    "short_code": "xk7p2qrm",
    "transfer_title": "Contrat signé",
    "status": "pending",
    "expires_at": "2026-06-09T14:32:00.000Z",
    "max_downloads": 3,
    "total_downloads": 0,
    "scan_status": "pending",
    "encryption_mode": "server",
    "created_at": "2026-06-06T14:32:00.000Z"
  },
  "upload_urls": [
    {
      "file_id": "contrat.pdf",
      "url": "https://storage.coffrify.com/uploads/…?X-Amz-Expires=3600&…",
      "headers": {
        "Content-Type": "application/pdf"
      }
    }
  ],
  "share_url": "https://files.coffrify.com/xk7p2qrm",
  "totp_secret": null
}

Erreurs

Voir aussi

• Créer votre premier transfert
• Créer une boîte de dépôt (Request Inbox)
• Gestion des erreurs et retry
• Rate limiting : quotas et en-têtes
• Référence complète de l'endpoint POST /v1/transfers