SDK Ruby

Cette page décrit comment intégrer Coffrify en Ruby. Un SDK Ruby officiel est en cours de préparation, mais il n'est pas encore publié. En attendant, l'API REST v1 reste pleinement utilisable depuis Ruby : tout passe par des requêtes HTTP classiques que vous pouvez écrire avec la bibliothèque standard net/http, sans aucune dépendance externe. Vous trouverez ci-dessous des exemples prêts à l'emploi pour créer un transfert chiffré, téléverser les fichiers, lister vos transferts et brancher un webhook, le tout dans l'idiome Ruby.

Pré-requis

Vous avez besoin d'une clé d'API et de la version de Ruby de votre choix (la bibliothèque net/http est incluse dans la bibliothèque standard, rien à installer). La base de l'API est https://api.coffrify.com/v1 et l'authentification se fait par un en-tête Authorization: Bearer <clé>. Utilisez une clé de test (cof_test_…) ou une clé sandbox (cof_sandbox_…) pendant le développement, puis une clé de production (cof_live_…) une fois en ligne. Ne placez jamais votre clé en clair dans le code : lisez-la depuis une variable d'environnement.

$ export COFFRIFY_API_KEY="cof_test_votre_cle_ici"
$ ruby --version

Créer un transfert

Le corps de la requête décrit les fichiers (files, avec name, size et mime_type) et les options de partage : durée de validité (expires_in_hours), nombre maximal de téléchargements (max_downloads), destinataire (recipient) et titre du transfert (transfer_title). La réponse contient un objet transfer, un tableau upload_urls et le share_url à communiquer. L'exemple suivant crée un transfert d'un fichier de 204 800 octets, valable 48 heures, adressé à un destinataire.

require "net/http"
require "uri"
require "json"
 
api_key = ENV.fetch("COFFRIFY_API_KEY")
uri = URI("https://api.coffrify.com/v1/transfers")
 
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{api_key}"
request["Content-Type"]  = "application/json"
# Idempotence : protège contre un double envoi en cas de nouvelle tentative
request["Idempotency-Key"] = "transfer-rapport-2026-06-#{Process.pid}"
 
request.body = JSON.generate(
  files: [
    { name: "rapport.pdf", size: 204_800, mime_type: "application/pdf" }
  ],
  expires_in_hours: 48,
  max_downloads: 3,
  recipient: "client@exemple.fr",
  transfer_title: "Rapport trimestriel"
)
 
response = http.request(request)
transfer = JSON.parse(response.body)
 
puts "Statut HTTP : #{response.code}"
puts "Lien de partage : #{transfer.dig("share_url")}"
 

La réponse a la forme suivante. Le tableau upload_urls associe à chaque fichier (file_id) une URL de dépôt et les en-têtes à renvoyer lors du téléversement. Le share_url est le lien que reçoit votre destinataire.

{
  "transfer": {
    "id": "trf_a1b2c3d4e5",
    "short_code": "a1b2c3",
    "status": "pending",
    "expires_at": "2026-06-12T10:30:00Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport.pdf",
      "url": "https://storage.coffrify.com/upload/...",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/a1b2c3"
}

Téléverser les fichiers

Une fois le transfert créé, envoyez le contenu de chaque fichier en PUT sur l'url correspondante, en reprenant exactement les headers fournis dans upload_urls. C'est le serveur Coffrify qui chiffre ensuite le contenu au repos (AES-256-GCM) : vous n'avez rien de particulier à faire côté Ruby. L'exemple poursuit la création précédente et téléverse le fichier local correspondant à chaque entrée.

# `transfer` provient de la réponse de création ci-dessus
transfer["upload_urls"].each do |item|
  put_uri  = URI(item["url"])
  put_http = Net::HTTP.new(put_uri.host, put_uri.port)
  put_http.use_ssl = (put_uri.scheme == "https")
 
  put_req = Net::HTTP::Put.new(put_uri)
  # Reprenez tels quels les en-têtes renvoyés par l'API
  item["headers"].each { |name, value| put_req[name] = value }
  put_req.body = File.binread(item["file_id"])
 
  put_resp = put_http.request(put_req)
  raise "Échec du téléversement de #{item["file_id"]}" unless put_resp.is_a?(Net::HTTPSuccess)
 
  puts "Fichier téléversé : #{item["file_id"]}"
end
 
puts "Transfert prêt. Partagez : #{transfer["share_url"]}"
 

Lister les transferts

require "net/http"
require "uri"
require "json"
 
api_key = ENV.fetch("COFFRIFY_API_KEY")
uri = URI("https://api.coffrify.com/v1/transfers")
uri.query = URI.encode_www_form(limit: 50)
 
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{api_key}"
 
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
 
page = JSON.parse(response.body)
page["data"].each { |t| puts "#{t["short_code"]} - #{t["status"]}" }
 
# Page suivante : réutilisez le curseur s'il est présent
if page["next_cursor"]
  puts "Curseur suivant : #{page["next_cursor"]}"
end
 

La réponse est un objet de liste contenant data (le tableau des transferts) et next_cursor. Tant que next_cursor n'est pas null, repassez-le dans le paramètre de requête cursor pour obtenir la page suivante. Pour récupérer ou supprimer un transfert précis, utilisez GET /v1/transfers/{id} et DELETE /v1/transfers/{id} sur le même modèle.

Recevoir les webhooks

Coffrify peut notifier votre application des événements (par défaut transfer.downloaded) en envoyant une requête POST signée à votre URL. Côté Ruby, exposez un endpoint qui lit le corps brut de la requête, vérifie la signature à l'aide du secret de l'endpoint (whsec_…, affiché une seule fois à la création), puis traite l'événement. Vérifiez toujours la signature avant de faire confiance au contenu. La création de l'endpoint se fait via POST /v1/webhooks ; la vérification de la signature suit le standard Standard Webhooks, dont la procédure complète figure dans la référence REST.

Dès que la gem coffrify pour Ruby sera disponible, cette page sera mise à jour avec l'installation et les méthodes idiomatiques. En attendant, ces appels REST couvrent l'ensemble du cycle de vie d'un transfert. Pour la liste exhaustive des paramètres, des codes d'erreur ({"error":{"code","message","request_id"}}), des en-têtes de limites de débit et de la vérification des webhooks, reportez-vous à la référence de l'API REST v1.