SDK Rust

Cette page explique comment utiliser l'API Coffrify depuis une application Rust. Le SDK Rust officiel est en cours de préparation. En attendant sa sortie, l'API REST v1 reste pleinement accessible : tout ce que fera le futur SDK, vous pouvez le faire dès aujourd'hui avec reqwest et serde. Vous trouverez ci-dessous des exemples async complets pour créer un transfert chiffré, téléverser les fichiers, lister vos transferts, et un mot sur les webhooks. Coffrify héberge vos données en Union européenne et chiffre chaque fichier au repos (RGPD).

Prérequis

Toutes les requêtes partent de la base https://api.coffrify.com/v1 et s'authentifient avec un en-tête Authorization: Bearer <clé>. Vos clés se créent dans le tableau de bord : cof_live_… pour la production, cof_test_… pour les tests, et cof_sandbox_… pour un environnement sandbox isolé de 24 h. Côté Rust, deux dépendances suffisent : reqwest (avec le support JSON) et serde.

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }

Créer un transfert

La création d'un transfert se fait en trois temps : vous décrivez d'abord les fichiers (nom, taille, type MIME) à POST /v1/transfers, l'API vous renvoie un objet transfer accompagné des upload_urls, puis vous téléversez chaque fichier en PUT vers son URL. Vous partagez ensuite le share_url. Pensez à envoyer un en-tête Idempotency-Key (8 à 255 caractères) sur cette écriture : si la requête est rejouée, l'API répond X-Coffrify-Idempotent-Replay: true au lieu de créer un doublon.

use serde_json::{json, Value};
 
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("COFFRIFY_API_KEY")?;
    let http = reqwest::Client::new();
 
    // 1. Décrire le(s) fichier(s) et créer le transfert.
    let created: Value = http
        .post("https://api.coffrify.com/v1/transfers")
        .bearer_auth(&api_key)
        .header("Idempotency-Key", "rapport-q3-2026-001")
        .json(&json!({
            "files": [
                { "name": "rapport.pdf", "size": 482_133, "mime_type": "application/pdf" }
            ],
            "expires_in_hours": 72,
            "recipient": "client@example.com",
            "transfer_title": "Rapport trimestriel"
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;
 
    let share_url = created["share_url"].as_str().unwrap_or_default();
    println!("Lien de partage : {share_url}");
 
    // 2. Téléverser chaque fichier vers son upload_url (voir section suivante).
    let upload = &created["upload_urls"][0];
    let bytes = std::fs::read("rapport.pdf")?;
    let mut put = http.put(upload["url"].as_str().unwrap()).body(bytes);
    if let Some(headers) = upload["headers"].as_object() {
        for (k, v) in headers {
            put = put.header(k, v.as_str().unwrap_or(""));
        }
    }
    put.send().await?.error_for_status()?;
 
    println!("Transfert prêt, partagez : {share_url}");
    Ok(())
}

La réponse contient un objet transfer (id, short_code, status, expires_at), la liste upload_urls (un élément { file_id, url, headers } par fichier), et le share_url à transmettre au destinataire. Le transfert n'est ni lisible ni partageable tant que le téléversement n'a pas eu lieu.

Téléverser les fichiers

Chaque entrée de upload_urls porte une url pré-signée et un objet headers. Faites un PUT du contenu binaire vers cette url en renvoyant exactement les headers fournis. N'ajoutez pas l'en-tête Authorization sur le PUT : l'URL est déjà signée. L'exemple Rust ci-dessus boucle sur headers puis envoie les octets ; voici la même étape isolée pour un fichier déjà créé.

// `upload` = un élément de created["upload_urls"]
let bytes = std::fs::read("rapport.pdf")?;
 
let mut req = http.put(upload["url"].as_str().unwrap()).body(bytes);
if let Some(headers) = upload["headers"].as_object() {
    for (name, value) in headers {
        req = req.header(name, value.as_str().unwrap_or(""));
    }
}
 
req.send().await?.error_for_status()?;
println!("Fichier téléversé.");

Lister les transferts

GET /v1/transfers renvoie vos transferts par pages. La pagination se fait par curseur : passez limit (100 au maximum) et reprenez avec le curseur renvoyé pour la page suivante. Récupérer ou supprimer un transfert précis se fait via GET /v1/transfers/{id} et DELETE /v1/transfers/{id}.

let page: serde_json::Value = http
    .get("https://api.coffrify.com/v1/transfers")
    .bearer_auth(&api_key)
    .query(&[("limit", "20")])
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
 
for t in page["data"].as_array().unwrap_or(&vec![]) {
    println!("{} - {}", t["short_code"], t["status"]);
}

Gérer les erreurs et les limites

En cas d'échec, l'API renvoie un corps { "error": { "code", "message", "request_id" } } que vous pouvez désérialiser pour journaliser le request_id. Surveillez aussi les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; sur un statut 429, respectez Retry-After (en secondes) avant de réessayer. Avec reqwest, appelez error_for_status() puis lisez le JSON d'erreur sur la branche Err pour récupérer ces détails.

Webhooks

Pour être notifié des événements (par défaut transfer.downloaded), créez un endpoint avec POST /v1/webhooks ; le secret de signature whsec_… n'est affiché qu'une seule fois, conservez-le. À la réception, vérifiez la signature au format Standard Webhooks (en-têtes webhook-id, webhook-timestamp, webhook-signature) ou via l'en-tête legacy X-Coffrify-Signature, en appliquant une tolérance de 5 minutes sur l'horodatage. Le calcul de signature se fait avec un crate HMAC-SHA256 côté Rust (par exemple hmac + sha2) ; la mécanique exacte est décrite dans la page Webhooks de la référence REST.