Coffrify, Transfert chiffré, stockage en France

Le SDK PHP officiel arrive bientôt ; en attendant, appelez l'API REST v1 de Coffrify directement en PHP avec cURL.

Le SDK PHP officiel de Coffrify est en cours de préparation. En attendant sa publication, vous n'avez besoin d'aucune dépendance particulière : l'API REST v1 s'appelle parfaitement depuis PHP avec l'extension cURL fournie en standard, ou avec n'importe quel client HTTP compatible PSR-18 (Guzzle, Symfony HttpClient). Cette page vous montre comment créer un transfert, téléverser les fichiers, lister vos transferts et brancher un webhook, en PHP idiomatique. Tous les exemples utilisent les vrais points d'entrée et les vrais formats de réponse ; vous pourrez les remplacer par le SDK le jour de sa sortie sans changer votre intégration.

Pré-requis

Il vous faut PHP 8.0 ou supérieur avec l'extension curl activée (présente par défaut dans la plupart des distributions), et une clé API. Toutes les requêtes passent par la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>. Utilisez une clé cof_test_… pendant le développement, puis cof_live_… en production. La clé secrète ne doit jamais quitter votre serveur : ne l'exposez pas dans du code côté navigateur.

Préfixe de clé	Usage
cof_live_…	Production
cof_test_…	Développement et tests
cof_sandbox_…	Bac à sable isolé, purgé après 24 h

Créer un transfert

POST/v1/transfersCrée un transfert et renvoie les URL de téléversement signées.

Vous déclarez d'abord les fichiers (nom, taille en octets, type MIME) et les options souhaitées (expires_in_hours, recipient, max_downloads, transfer_title, password). La réponse contient le transfer créé, la liste upload_urls (une entrée par fichier, avec son url et ses headers) et l'share_url à partager. Pensez à renseigner l'en-tête Idempotency-Key (8 à 255 caractères) : si vous rejouez la même requête, Coffrify renvoie le transfert déjà créé plutôt que d'en créer un second, et signale le rejeu via X-Coffrify-Idempotent-Replay: true.

<?php
 
$apiKey = getenv('COFFRIFY_API_KEY'); // cof_live_… ou cof_test_…
$path   = '/Users/moi/rapport-q4.pdf';
 
$payload = [
    'files' => [[
        'name'      => basename($path),
        'size'      => filesize($path),
        'mime_type' => mime_content_type($path) ?: 'application/octet-stream',
    ]],
    'expires_in_hours' => 168,            // 7 jours
    'max_downloads'    => 10,
    'recipient'        => 'client@exemple.fr',
    'transfer_title'   => 'Rapport Q4',
];
 
$ch = curl_init('https://api.coffrify.com/v1/transfers');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
 
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($status >= 400) {
    $err = json_decode($body, true);
    throw new RuntimeException($err['error']['message'] ?? 'Échec de création du transfert');
}
 
$transfer = json_decode($body, true);
echo 'Lien de partage : ' . $transfer['share_url'] . PHP_EOL;

La réponse a la forme suivante. Notez que chaque entrée de upload_urls correspond à un fichier dans le même ordre que celui de votre tableau files, et fournit les headers exacts à renvoyer lors du téléversement.

{
  "transfer": {
    "id": "tr_3f9a…",
    "short_code": "a1B2c3",
    "status": "pending",
    "expires_at": "2026-06-17T09:00:00Z"
  },
  "upload_urls": [
    {
      "file_id": "rapport-q4.pdf",
      "url": "https://…/upload?signature=…",
      "headers": { "Content-Type": "application/octet-stream" }
    }
  ],
  "share_url": "https://files.coffrify.com/a1B2c3"
}

Téléverser les fichiers

Pour chaque entrée de upload_urls, envoyez le contenu binaire du fichier en PUT sur son url, en appliquant tels quels tous les headers retournés. N'ajoutez ni Authorization ni en-tête supplémentaire sur cette requête : l'URL est déjà signée et chaque en-tête fourni fait partie de la signature. Une réponse 200 confirme la réception. Une fois tous les fichiers téléversés, le transfert devient actif et l'share_url est consultable.

<?php
 
// $transfer provient de l'étape précédente.
$files = [ 'rapport-q4.pdf' => '/Users/moi/rapport-q4.pdf' ];
 
foreach ($transfer['upload_urls'] as $slot) {
    $localPath = $files[$slot['file_id']];
    $contents  = file_get_contents($localPath);
 
    // Reprend exactement les en-têtes renvoyés par l'API.
    $headers = [];
    foreach ($slot['headers'] as $name => $value) {
        $headers[] = $name . ': ' . $value;
    }
 
    $ch = curl_init($slot['url']);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => 'PUT',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_POSTFIELDS     => $contents,
    ]);
 
    curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
 
    if ($status >= 400) {
        throw new RuntimeException("Échec du téléversement de {$slot['file_id']} (HTTP $status)");
    }
}
 
echo 'Transfert prêt : ' . $transfer['share_url'] . PHP_EOL;

Lister les transferts

GET/v1/transfersListe paginée par curseur (limit jusqu'à 100).

La pagination se fait par curseur. Passez limit (au maximum 100) et, pour la page suivante, le next_cursor renvoyé par la réponse précédente. Le champ has_more indique s'il reste des résultats à parcourir.

<?php
 
$apiKey = getenv('COFFRIFY_API_KEY');
$cursor = null;
 
do {
    $url = 'https://api.coffrify.com/v1/transfers?limit=50';
    if ($cursor !== null) {
        $url .= '&cursor=' . urlencode($cursor);
    }
 
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
    ]);
    $page = json_decode(curl_exec($ch), true);
    curl_close($ch);
 
    foreach ($page['data'] as $t) {
        printf("%s  %s  %s\n", $t['short_code'], $t['status'], $t['created_at']);
    }
 
    $cursor = $page['next_cursor'] ?? null;
} while (!empty($page['has_more']));

Pour récupérer ou supprimer un transfert précis, appelez GET /v1/transfers/{id} ou DELETE /v1/transfers/{id} avec le même en-tête Authorization. La suppression révoque immédiatement l'share_url.

Webhooks

Pour être notifié des événements (par défaut transfer.downloaded), créez un webhook via POST /v1/webhooks avec un name et l'url de votre endpoint. La réponse contient le secret (préfixé whsec_…), affiché une seule fois : conservez-le, il sert à vérifier la signature des messages que Coffrify enverra à votre serveur.

<?php
 
$apiKey = getenv('COFFRIFY_API_KEY');
 
$ch = curl_init('https://api.coffrify.com/v1/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'name'   => 'Notifications de téléchargement',
        'url'    => 'https://app.exemple.fr/webhooks/coffrify',
        'events' => ['transfer.downloaded'],
    ]),
]);
 
$webhook = json_decode(curl_exec($ch), true);
curl_close($ch);
 
// À stocker de manière sûre : il ne sera plus jamais affiché.
echo 'Secret : ' . $webhook['secret'] . PHP_EOL;

À la réception, vérifiez la signature avant de traiter le message. Coffrify envoie les en-têtes webhook-id, webhook-timestamp et webhook-signature. Recalculez un HMAC-SHA256 sur la chaîne id.timestamp.corps avec votre secret, comparez-le à la signature reçue, et rejetez tout horodatage qui s'écarte de plus de cinq minutes de l'heure courante.

<?php
 
$secret  = getenv('COFFRIFY_WEBHOOK_SECRET'); // whsec_…
$payload = file_get_contents('php://input');
$id      = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$sigHdr  = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';
 
// Rejette les messages trop anciens (tolérance 5 min).
if (abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit('Horodatage hors tolérance');
}
 
$signed   = $id . '.' . $ts . '.' . $payload;
$expected = 'v1,' . base64_encode(hash_hmac('sha256', $signed, $secret, true));
 
// L'en-tête peut contenir plusieurs signatures séparées par une espace.
$valid = false;
foreach (explode(' ', $sigHdr) as $candidate) {
    if (hash_equals($expected, $candidate)) {
        $valid = true;
        break;
    }
}
 
if (!$valid) {
    http_response_code(400);
    exit('Signature invalide');
}
 
$event = json_decode($payload, true);
// … traitez $event ici …
http_response_code(200);

Et ensuite

Ces appels couvrent l'essentiel : créer un transfert, téléverser, lister et recevoir des webhooks. Pour le détail complet des paramètres, des codes d'erreur ({"error":{"code","message","request_id"}}), des en-têtes de limitation de débit (X-RateLimit-Remaining, Retry-After) et de la Réception (intake), reportez-vous à la référence REST. Dès que le SDK PHP officiel sera publié, vous pourrez migrer ce code vers les classes natives sans changer un seul point d'entrée.