SDK .NET / C#

Cette page vous montre comment intégrer Coffrify dans une application .NET / C# dès aujourd'hui. Un SDK .NET officiel est en préparation, mais il n'est pas encore publié. En attendant, vous appelez directement l'API REST v1 avec le HttpClient de la bibliothèque standard et le modèle async/await. Toutes les capacités de la plateforme (créer un transfert chiffré, téléverser les fichiers, lister, supprimer, recevoir des webhooks) sont accessibles ainsi, sans dépendance externe.

Principes

L'API REST a pour base https://api.coffrify.com/v1. Chaque requête s'authentifie avec un en-tête Authorization: Bearer <clé>, où la clé est de la forme cof_live_… en production ou cof_test_… en test. Les réponses et les corps de requête sont au format JSON. En .NET, vous pouvez réutiliser une instance unique de HttpClient pour l'ensemble de vos appels et y fixer une fois pour toutes l'en-tête d'autorisation.

using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
 
var http = new HttpClient { BaseAddress = new Uri("https://api.coffrify.com/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("COFFRIFY_API_KEY"));

Créer un transfert

Vous décrivez les fichiers à envoyer (nom, taille en octets, type MIME) et, en option, une durée d'expiration via expires_in_hours et un destinataire via recipient. La réponse contient l'objet transfer (avec id, short_code, status, expires_at), un tableau upload_urls (une entrée par fichier, avec file_id, url et headers) et le share_url à communiquer au destinataire.

using System.Text.Json;
 
var payload = new
{
    files = new[]
    {
        new { name = "contrat.pdf", size = 284512, mime_type = "application/pdf" }
    },
    expires_in_hours = 72,
    recipient = "client@exemple.com",
    transfer_title = "Contrat de prestation"
};
 
var create = await http.PostAsJsonAsync("v1/transfers", payload);
create.EnsureSuccessStatusCode();
 
using var doc = JsonDocument.Parse(await create.Content.ReadAsStringAsync());
var root = doc.RootElement;
 
var shareUrl = root.GetProperty("share_url").GetString();
Console.WriteLine($"Lien de partage : {shareUrl}");

Téléverser les fichiers

La création du transfert ne transporte pas encore les octets. Pour chaque entrée de upload_urls, vous effectuez une requête PUT vers son url en envoyant le contenu du fichier et en reprenant exactement les headers fournis. Faites correspondre chaque fichier à son file_id. Une fois tous les téléversements terminés, le transfert devient téléchargeable via le share_url.

// Pour chaque entrée de upload_urls renvoyée à l'étape précédente :
var uploads = root.GetProperty("upload_urls");
 
foreach (var item in uploads.EnumerateArray())
{
    var url = item.GetProperty("url").GetString();
    var bytes = await File.ReadAllBytesAsync("contrat.pdf");
 
    using var content = new ByteArrayContent(bytes);
    // Reprenez les en-têtes fournis (au minimum Content-Type).
    foreach (var header in item.GetProperty("headers").EnumerateObject())
    {
        content.Headers.Remove(header.Name);
        content.Headers.TryAddWithoutValidation(header.Name, header.Value.GetString());
    }
 
    var put = await http.PutAsync(url, content);
    put.EnsureSuccessStatusCode();
}

Lister et supprimer

GET /v1/transfers renvoie vos transferts paginés par curseur (limit jusqu'à 100, cursor pour la page suivante). GET /v1/transfers/{id} récupère un transfert précis et DELETE /v1/transfers/{id} le supprime. Les mêmes appels se font naturellement avec GetFromJsonAsync et DeleteAsync.

// Lister (page de 50)
var list = await http.GetFromJsonAsync<JsonElement>("v1/transfers?limit=50");
foreach (var t in list.GetProperty("data").EnumerateArray())
{
    Console.WriteLine($"{t.GetProperty("id").GetString()} - {t.GetProperty("status").GetString()}");
}
 
// Supprimer un transfert
var del = await http.DeleteAsync("v1/transfers/tr_8f2c1a");
del.EnsureSuccessStatusCode();

Gérer les erreurs

En cas d'échec, la réponse a un statut HTTP non 2xx et un corps JSON de la forme {"error":{"code":"…","message":"…","request_id":"…"}}. Le request_id est précieux pour le support. Pour le débit, surveillez les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset ; sur un statut 429, respectez le délai indiqué par Retry-After avant de réessayer.

if (!create.IsSuccessStatusCode)
{
    using var err = JsonDocument.Parse(await create.Content.ReadAsStringAsync());
    var e = err.RootElement.GetProperty("error");
    Console.WriteLine($"[{e.GetProperty("code").GetString()}] " +
                      $"{e.GetProperty("message").GetString()} " +
                      $"(request_id: {e.GetProperty("request_id").GetString()})");
}

Webhooks

Pour être notifié des événements (par exemple transfer.downloaded), créez un endpoint avec POST /v1/webhooks. Le secret de signature whsec_… n'est affiché qu'une seule fois à la création : conservez-le. À la réception, vérifiez la signature en recalculant un HMAC-SHA256 avec ce secret, en respectant la tolérance d'horodatage de 5 minutes, puis répondez 200. Une réception ASP.NET typique lit le corps brut, vérifie la signature, puis traite l'événement.

Pour la liste complète des champs acceptés, des codes d'erreur et des en-têtes de débit, reportez-vous à la référence REST de l'API v1. Si vous travaillez aussi en JavaScript ou Node, le SDK coffrify est déjà publié sur npm et expose les mêmes opérations en quelques lignes.