SDK Python

Cette page décrit l'usage de Coffrify en Python. Le SDK Python officiel est en cours de préparation. En attendant sa sortie, vous n'avez besoin d'aucune dépendance spécifique à Coffrify : l'API REST v1 s'appelle parfaitement avec la librairie HTTP standard de l'écosystème Python, à savoir requests. Les exemples ci-dessous montrent comment créer un transfert chiffré, téléverser les fichiers, lister vos transferts et recevoir des webhooks, en pur Python, exactement comme le fera le futur SDK sous le capot.

Prérequis

Vous avez besoin d'une clé d'API (préfixe cof_live_… en production, cof_test_… en test) disponible depuis votre tableau de bord, et de la librairie requests. L'authentification se fait par l'en-tête Authorization: Bearer <clé>. La base de l'API est https://api.coffrify.com/v1.

$ pip install requests

Conservez votre clé hors du code source, par exemple dans une variable d'environnement COFFRIFY_API_KEY. Ne la committez jamais dans un dépôt.

Créer un transfert

Un transfert se crée en deux temps : vous déclarez d'abord les fichiers (nom, taille, type MIME) et les options, puis vous téléversez le contenu vers les URL renvoyées. Le corps accepte notamment files, expires_in_hours, max_downloads, password, recipient et transfer_title. Le chiffrement AES-256-GCM côté serveur est appliqué par défaut, vous n'avez rien à gérer.

import os
import requests
 
API = "https://api.coffrify.com/v1"
KEY = os.environ["COFFRIFY_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
 
payload = {
    "files": [
        {"name": "contrat.pdf", "size": 482113, "mime_type": "application/pdf"},
    ],
    "expires_in_hours": 72,
    "recipient": "client@example.com",
    "transfer_title": "Contrat a signer",
}
 
resp = requests.post(f"{API}/transfers", json=payload, headers=HEADERS)
resp.raise_for_status()
data = resp.json()
 
transfer = data["transfer"]
print("Lien de partage :", data["share_url"])
print("Identifiant     :", transfer["id"], transfer["short_code"])

La réponse contient l'objet transfer (avec id, short_code, status, expires_at), un tableau upload_urls et le share_url à transmettre à votre destinataire.

Téléverser les fichiers

Chaque entrée de upload_urls fournit un file_id, une url et un dictionnaire headers. Pour chaque fichier, envoyez son contenu en PUT vers l'url correspondante, en reprenant les headers indiqués tels quels. Tant qu'aucun fichier n'est téléversé, le transfert n'est pas distribuable.

# Associez chaque fichier local a son URL de televersement.
# Ici, un seul fichier : on prend la premiere URL renvoyee.
upload = data["upload_urls"][0]
 
with open("contrat.pdf", "rb") as f:
    put = requests.put(upload["url"], data=f, headers=upload["headers"])
    put.raise_for_status()
 
print("Televersement termine. Partagez :", data["share_url"])

Lister les transferts

La liste est paginée par curseur. Indiquez limit (100 au maximum) et faites suivre le cursor renvoyé pour récupérer la page suivante.

resp = requests.get(
    f"{API}/transfers",
    params={"limit": 50},
    headers=HEADERS,
)
resp.raise_for_status()
page = resp.json()
 
for t in page["data"]:
    print(t["short_code"], t["status"], t["expires_at"])
 
# Page suivante, si un curseur est renvoye :
next_cursor = page.get("next_cursor")
if next_cursor:
    requests.get(f"{API}/transfers",
                 params={"limit": 50, "cursor": next_cursor},
                 headers=HEADERS)

Idempotence et limites de débit

Sur les écritures (comme la création d'un transfert), ajoutez un en-tête Idempotency-Key (de 8 à 255 caractères) pour pouvoir rejouer une requête sans la dupliquer. Surveillez aussi les en-têtes X-RateLimit-Remaining et, en cas de réponse 429, respectez Retry-After.

import uuid
 
resp = requests.post(
    f"{API}/transfers",
    json=payload,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
)
 
if resp.status_code == 429:
    wait = int(resp.headers.get("Retry-After", "1"))
    print(f"Limite atteinte, reessayez dans {wait} s")

Recevoir des webhooks

Coffrify peut notifier votre serveur lors d'événements comme transfer.downloaded. Le secret de signature (whsec_…) vous est montré une seule fois à la création du webhook. À chaque notification, vérifiez la signature avant de traiter le corps, en recalculant un HMAC-SHA256 avec votre secret, avec une tolérance de 5 minutes sur l'horodatage.

import hmac, hashlib, base64
 
def verifier_signature(secret: str, webhook_id: str, timestamp: str,
                       body: bytes, signature_header: str) -> bool:
    # secret au format whsec_<base64> : on decode la partie base64.
    cle = base64.b64decode(secret.split("_", 1)[1])
    a_signer = f"{webhook_id}.{timestamp}.".encode() + body
    attendu = base64.b64encode(
        hmac.new(cle, a_signer, hashlib.sha256).digest()
    ).decode()
    # L'en-tete peut contenir plusieurs signatures "v1,<sig>" separees par un espace.
    for partie in signature_header.split():
        version, _, sig = partie.partition(",")
        if version == "v1" and hmac.compare_digest(sig, attendu):
            return True
    return False

Pensez à comparer l'horodatage webhook-timestamp à l'heure courante et à rejeter les requêtes hors de la fenêtre de 5 minutes, afin de prévenir les rejeux.