SDK Java / JVM

Cette page concerne l'usage de Coffrify depuis le JVM (Java, et par extension Kotlin ou Scala). Un SDK Java officiel est en préparation, mais il n'est pas encore publié. En attendant, vous pouvez utiliser l'intégralité de l'API REST v1 directement depuis votre application, en vous appuyant sur le client HTTP intégré au JDK, java.net.http.HttpClient (disponible depuis Java 11). Les exemples ci-dessous montrent comment créer un transfert, téléverser les fichiers, lister vos transferts et recevoir les webhooks, sans dépendance externe.

Prérequis

Vous avez besoin de Java 11 ou plus récent (pour java.net.http.HttpClient) et d'une clé API. Les clés de test commencent par cof_test_, les clés de production par cof_live_. Toutes les requêtes passent par la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>. Ne placez jamais une clé cof_live_ dans du code livré côté client : conservez-la sur votre serveur, par exemple via une variable d'environnement.

• Base de l'API : https://api.coffrify.com/v1
• Authentification : en-tête Authorization: Bearer <clé>
• Pour créer un transfert, votre clé doit disposer du scope transfers:write
• Sur les écritures, ajoutez l'en-tête Idempotency-Key (8 à 255 caractères) pour pouvoir rejouer une requête sans risque de doublon

Créer un transfert

Vous décrivez les fichiers (name, size, mime_type) et, en option, la durée de validité (expires_in_hours), un destinataire (recipient), un titre (transfer_title), un mot de passe (password) ou une limite de téléchargements (max_downloads). La réponse contient l'objet transfer (avec son id, son short_code, son share_url et sa date d'expiration) et un tableau upload_urls : un élément par fichier, dans le même ordre que le tableau files envoyé.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class CreateTransfer {
  static final HttpClient client = HttpClient.newHttpClient();
  static final String API_KEY = System.getenv("COFFRIFY_API_KEY");
 
  public static void main(String[] args) throws Exception {
    String body = """
      {
        "files": [
          { "name": "contrat.pdf", "size": 248137, "mime_type": "application/pdf" }
        ],
        "expires_in_hours": 72,
        "recipient": "client@example.com",
        "transfer_title": "Contrat de prestation"
      }
      """;
 
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.coffrify.com/v1/transfers"))
        .header("Authorization", "Bearer " + API_KEY)
        .header("Content-Type", "application/json")
        .header("Idempotency-Key", "transfer-contrat-2026-06-10")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
 
    HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
 
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

Pour parser la réponse JSON, utilisez la bibliothèque de votre choix (Jackson, Gson, ou le JSONObject de votre stack). Les exemples ci-dessus laissent volontairement le corps de réponse en texte brut afin de rester sans dépendance ; en pratique, récupérez transfer.id, transfer.share_url et le tableau upload_urls pour la suite.

Téléverser les fichiers

Chaque entrée de upload_urls fournit un file_id, une url et un objet headers. Vous envoyez le contenu du fichier en PUT vers cette url, en reprenant tels quels les en-têtes renvoyés. Ces URL sont à usage direct et temporaire : ne réécrivez pas l'en-tête Authorization dessus, et appliquez exactement les headers fournis par l'API.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
import java.util.Map;
 
// uploadUrl et uploadHeaders proviennent d'un élément de upload_urls.
String uploadUrl = "https://..."; // upload_urls[0].url
Map<String, String> uploadHeaders = Map.of(
    "Content-Type", "application/pdf"); // upload_urls[0].headers
 
HttpClient client = HttpClient.newHttpClient();
 
HttpRequest.Builder put = HttpRequest.newBuilder()
    .uri(URI.create(uploadUrl))
    .PUT(HttpRequest.BodyPublishers.ofFile(Path.of("contrat.pdf")));
 
uploadHeaders.forEach(put::header);
 
HttpResponse<Void> upload =
    client.send(put.build(), HttpResponse.BodyHandlers.discarding());
 
if (upload.statusCode() >= 200 && upload.statusCode() < 300) {
  System.out.println("Fichier televerse.");
}

Une fois tous les fichiers téléversés, le transfert est prêt. Partagez simplement le share_url renvoyé à la création : c'est le lien que votre destinataire ouvrira pour télécharger les fichiers.

Lister les transferts

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
HttpClient client = HttpClient.newHttpClient();
String apiKey = System.getenv("COFFRIFY_API_KEY");
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.coffrify.com/v1/transfers?limit=20"))
    .header("Authorization", "Bearer " + apiKey)
    .GET()
    .build();
 
HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
 
System.out.println(response.body());
// Pour la page suivante, repassez le curseur renvoye via ?cursor=...

Pour récupérer ou supprimer un transfert précis, appelez GET /v1/transfers/{id} ou DELETE /v1/transfers/{id} selon le même modèle : reprenez le code ci-dessus en remplaçant l'URI et, pour la suppression, en utilisant .DELETE() à la place de .GET().

Webhooks

Vous pouvez recevoir des notifications d'événements (par exemple transfer.downloaded) sur une URL HTTPS de votre application. Côté JVM, exposez un endpoint avec votre framework habituel (Spring, Javalin, ou un simple HttpServer) et vérifiez la signature de chaque requête avant de traiter la charge utile. Coffrify signe selon le standard *Standard Webhooks* (en-têtes webhook-id, webhook-timestamp, webhook-signature) et accepte une tolérance d'horloge de 5 minutes.

• Créez l'abonnement via POST /v1/webhooks (par défaut, l'événement transfer.downloaded).
• Le secret de signature whsec_... n'est affiché qu'une seule fois à la création : stockez-le immédiatement.
• À la réception, recalculez un HMAC-SHA256 avec ce secret et comparez-le à l'en-tête webhook-signature avant d'agir.
• Rejetez toute requête dont l'horodatage s'écarte de plus de 5 minutes de l'heure courante.

Aller plus loin

Tous les autres points de l'API (Réception / intake, coffres, gestion des clés, export RGPD) sont accessibles depuis le JVM selon le même schéma : une requête HttpRequest, l'en-tête Authorization: Bearer, et un en-tête Idempotency-Key sur les écritures. Consultez la référence REST pour la liste complète des points d'accès, des champs et des codes d'erreur, dont le format est {"error":{"code":"...","message":"...","request_id":"..."}}. Dès que le SDK Java officiel sera disponible, cette page sera mise à jour avec les instructions d'installation et les exemples idiomatiques.