Intégrer le SDK Go dans une application serveur

Apprenez à installer le SDK Go de Coffrify, à vous authentifier avec une clé API et à créer des transferts, inscrire des webhooks et interroger le contexte de votre clé depuis une application serveur Go.

Télécharger en PDF

Ce guide explique comment utiliser le SDK Go de Coffrify dans une application serveur : initialisation du client, création d'un transfert (avec URLs d'upload pré-signées), inscription d'un webhook et interrogation du contexte de la clé via GET /v1/me. Chaque appel est authentifié par un en-tête Authorization: Bearer <clé> ; le SDK gère automatiquement les en-têtes X-Request-Id, X-Coffrify-Api-Version et les limites de débit renvoyées dans X-RateLimit-*.

GET/v1/meRetourne le contexte de la clé API courante : workspace, scopes accordés et environnement (live / test / sandbox).POST/v1/transfersCrée un transfert et retourne les URLs d'upload pré-signées pour chaque fichier déclaré.GET/v1/transfersListe les transferts du workspace avec pagination par curseur, filtres de statut et de dossier.POST/v1/webhooksInscrit un nouvel endpoint webhook et retourne le secret de signature HMAC à conserver côté serveur.

Authentification

Toutes les routes de l'API (sauf /v1/welcome) exigent un en-tête Authorization: Bearer <clé>. Trois préfixes sont acceptés selon l'environnement : cof_live_… pour la production, cof_test_… pour les tests (données réelles, sans facturation), et cof_sandbox_… pour le bac à sable éphémère (plafonnés : 10 fichiers par transfert, 10 Mo par fichier, 25 transferts par 24 h). Les clés restreintes utilisent le préfixe cof_rk_live_… ou cof_rk_test_… avec un sous-ensemble de scopes. Un identifiant de requête stable peut être fourni via l'en-tête X-Request-Id pour faciliter le débogage dans la console Coffrify. Pour GET /v1/me, aucun scope particulier n'est requis. Pour GET /v1/transfers, le scope transfers:read est nécessaire. Pour POST /v1/transfers, le scope transfers:write est requis. Pour POST /v1/webhooks, PATCH /v1/webhooks et DELETE /v1/webhooks, le scope webhooks:manage est requis.

Installation

Le SDK Go s'installe avec go get. La commande ci-dessous récupère la dernière version stable.

$ go get github.com/coffrify/coffrify-go@latest

Corps de la requête, POST /v1/transfers

La création de transfert reprend les champs de l'API standard ; seul files est obligatoire. Le tableau ci-dessous détaille les champs acceptés.

Champ	Type	Requis	Description
files	array	Oui	Liste des fichiers à uploader. Chaque élément doit contenir `name` (string), `size` (int, octets) et optionnellement `mime_type` (string, défaut : `application/octet-stream`).
expires_in_hours	integer	Non	Durée de validité en heures. Laissez vide pour utiliser la valeur par défaut du workspace.
max_downloads	integer	Non	Nombre maximal de téléchargements autorisés. En sandbox, plafonné à 5.
password	string	Non	Mot de passe de protection. Le contenu est chiffré AES-256-GCM côté serveur.
transfer_title	string	Non	Titre affiché au destinataire. Alias acceptés : `title`, `transferTitle`.
recipient	string	Non	Adresse e-mail du destinataire pour l'envoi automatique du lien.
allow_download	boolean	Non	Autoriser le téléchargement direct des fichiers (défaut : true).
auto_delete	boolean	Non	Supprimer le transfert après le dernier téléchargement autorisé.
notes	string	Non	Message personnel joint au transfert.
custom_slug	string	Non	Identifiant court personnalisé dans l'URL de partage (plan Pro requis).
notify_opens	boolean	Non	Envoyer une notification e-mail à l'expéditeur à chaque ouverture.
watermark_enabled	boolean	Non	Afficher un filigrane sur les fichiers prévisualisés (plan Ultra).
watermark_text	string	Non	Texte du filigrane (si `watermark_enabled` est true).
geo_allowlist	array<string>	Non	Codes pays ISO 3166-1 alpha-2 autorisés (plan Ultra).
geo_blocklist	array<string>	Non	Codes pays ISO 3166-1 alpha-2 bloqués (plan Ultra).
encryption_mode	string	Non	Mode de chiffrement : `standard` (AES-256-GCM serveur) ou `e2e` (zéro-connaissance, clé client).
require_totp	boolean	Non	Exiger un code TOTP pour accéder au transfert. Le secret est retourné dans `totp_secret`.

Exemples d'appels

Les exemples ci-dessous initialisent le client, créent un transfert, puis inscrivent un webhook. L'onglet Go est le plus pertinent ici.

# 1. Vérifier le contexte de la clé
curl -s https://api.coffrify.com/v1/me \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# 2. Créer un transfert (2 fichiers)
curl -s -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "files": [
      {"name": "rapport.pdf", "size": 204800, "mime_type": "application/pdf"},
      {"name": "donnees.xlsx", "size": 51200, "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"}
    ],
    "transfer_title": "Rapport Q2 2026",
    "expires_in_hours": 72,
    "max_downloads": 3,
    "recipient": "client@exemple.com"
  }'
 
# 3. Inscrire un webhook
curl -s -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notifications transferts",
    "url": "https://mon-serveur.exemple.com/hooks/coffrify",
    "events": ["transfer.downloaded", "transfer.expired"]
  }'

Réponse, POST /v1/transfers

La réponse renvoie l'objet transfer et les upload_urls à utiliser tout de suite pour téléverser. Conservez l'id du transfert et le share_url à transmettre.

{
  "transfer": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_code": "xK9mP2",
    "transfer_title": "Rapport Q2 2026",
    "status": "active",
    "expires_at": "2026-06-09T14:32:00.000Z",
    "max_downloads": 3,
    "total_downloads": 0,
    "scan_status": "pending",
    "encryption_mode": "standard",
    "created_at": "2026-06-06T14:32:00.000Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport.pdf",
      "url": "https://storage.coffrify.com/uploads/a1b2c3d4/rapport.pdf?X-Amz-Signature=abc123...",
      "headers": {
        "Content-Type": "application/pdf"
      }
    }
  ],
  "share_url": "https://files.coffrify.com/xK9mP2",
  "totp_secret": null
}

Réponse, POST /v1/webhooks

{
  "id": "wh_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "Notifications transferts",
  "description": null,
  "url": "https://mon-serveur.exemple.com/hooks/coffrify",
  "events": ["transfer.downloaded", "transfer.expired"],
  "is_active": true,
  "signing_version": "v1",
  "retry_policy": null,
  "created_at": "2026-06-06T14:35:00.000Z",
  "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Réponse, GET /v1/me

{
  "workspace": {
    "id": "ws_c3d4e5f6-a7b8-9012-cdef-345678901234",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "pro",
    "is_personal": false
  },
  "api_key": {
    "id": "key_d4e5f6a7-b8c9-0123-defa-456789012345",
    "name": "Serveur de production",
    "key_prefix": "cof_live_xxxx",
    "scopes": ["transfers:read", "transfers:write", "webhooks:manage"],
    "environment": "live",
    "last_used_at": "2026-06-06T14:32:00.000Z",
    "created_at": "2026-01-15T09:00:00.000Z"
  },
  "scopes": ["transfers:read", "transfers:write", "webhooks:manage"],
  "environment": "live"
}

Erreurs

Le SDK Go renvoie une erreur typée par catégorie. Le tableau ci-dessous récapitule les codes HTTP, leur cause et la résolution.

Code HTTP	code (JSON)	Quand	Résolution
400	`validation_error`	`files[]` absent ou vide dans le corps, `name` ou `url` manquants pour un webhook, URL de webhook invalide, type d'événement inconnu.	Vérifiez que le corps est un objet JSON valide et que tous les champs obligatoires sont présents.
401	`invalid_api_key`	Clé absente, préfixe non reconnu (doit commencer par `cof_live_`, `cof_test_`, `cof_sandbox_`, `cof_rk_` ou `cof_mcp_`).	Regénérez la clé dans l'espace développeur : `https://app.coffrify.com/developer`.
401	`expired_api_key`	La clé a dépassé sa date d'expiration ou le quota max d'usages.	Créez une nouvelle clé ou prolongez l'expiration dans la console.
401	`revoked_api_key`	La clé a été révoquée manuellement ou désactivée.	Provisionnez une nouvelle clé avec les scopes nécessaires.
403	`scope_missing`	Le scope requis (`transfers:write`, `webhooks:manage`, etc.) n'est pas accordé à cette clé.	Rééditez la clé avec le scope manquant ou utilisez `cof_rk_*` avec le bon périmètre.
403	`ip_not_allowed`	L'IP source n'est pas dans la liste d'autorisation de la clé.	Ajoutez l'IP du serveur dans les restrictions IP de la clé.
409	`validation_error`	Maximum de 25 webhooks par workspace atteint.	Supprimez un webhook inutilisé via `DELETE /v1/webhooks`.
422	`validation_error`	En sandbox : plus de 10 fichiers par transfert ou fichier dépassant 10 Mo.	Réduisez le nombre de fichiers ou leur taille pour respecter les plafonds sandbox.
429	`rate_limited`	Quota de requêtes par minute dépassé ou quota de 25 transferts sandbox par 24 h atteint.	Respectez l'en-tête `Retry-After` renvoyé dans la réponse. En sandbox, attendez la fin de la fenêtre de 24 h.
500	`internal_error`	Erreur interne du serveur.	Réessayez après quelques secondes. Si l'erreur persiste, contactez le support avec le `request_id` de la réponse.

Bonnes pratiques Go

Idempotence : transmettez un en-tête Idempotency-Key unique (UUID v4) sur chaque appel POST /v1/transfers ; si votre goroutine est interrompue et relancée, l'API retournera la réponse originale sans créer de doublon. Variables d'environnement : stockez votre clé dans COFFRIFY_API_KEY et ne la codez jamais en dur. En CI/CD, utilisez cof_test_… pour les environnements de staging. Vérification HMAC des webhooks : conservez le champ secret (préfixé whsec_) renvoyé à la création du webhook. Côté réception, calculez HMAC-SHA256(secret, corps_brut) et comparez avec l'en-tête X-Coffrify-Signature avant de traiter l'événement. Retry avec back-off exponentiel : les erreurs 429 incluent un en-tête Retry-After exprimé en secondes. Implémentez un back-off exponentiel avec jitter pour éviter les rafales synchronisées entre goroutines. Isolation sandbox : une clé cof_sandbox_… ne voit que les transferts créés avec cette même clé. Les ressources sandbox sont auto-purgées toutes les 24 h et ne sont pas facturées.

Voir aussi

Référence complète de l'API
Authentification et scopes
Événements webhook disponibles
Vérifier la signature HMAC d'un webhook
Créer un transfert E2E (zéro-connaissance)
Pagination par curseur
Limites de débit et quotas

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→