Connectez BLEME à vos outils

Toutes les requêtes se font en HTTPS vers la base ci-dessous. Les réponses sont en JSON (UTF-8). Les montants sont toujours en centimes (entiers), les dates en ISO 8601.

https://bleme.fr/api/v1

1. 1. Dans BLEME, ouvrez Paramètres → Clés API et créez une clé en cochant les droits voulus.
2. 2. Copiez la clé blm_live_… — elle n’est affichée qu’une seule fois.
3. 3. Passez-la dans l’en-tête Authorization de chaque requête.

curl https://bleme.fr/api/v1/cases \
  -H "Authorization: Bearer $BLEME_KEY"

L’API et les webhooks font partie du forfait Pro.

Chaque requête porte l’en-tête Authorization: Bearer VOTRE_CLÉ. La clé est liée à une organisation et à un jeu de droits (scopes) figé à sa création — elle ne peut rien faire de plus que ces droits, même si vous êtes propriétaire.

Une clé se révoque à tout moment depuis le même écran ; elle est aussi révoquée automatiquement si son créateur perd l’accès à l’organisation.

Pagination

Les listes sont paginées par curseur. Chaque réponse renvoie data et next_cursor (ou null en fin de liste). Passez ce curseur au paramètre cursor de la requête suivante. limit : 25 par défaut, 100 maximum.

{
  "data": [ /* … */ ],
  "next_cursor": "eyJ…"
}

Erreurs

Les erreurs renvoient un statut HTTP et un corps normalisé { "error": { "code", "message" } }.

Limites

120 requêtes par minute et par clé. Au-delà, réponse 429 avec l’en-tête Retry-After (secondes).

Plutôt que d’interroger l’API en boucle, laissez BLEME notifier votre outil quand un événement se produit. Créez un endpoint dans Paramètres → Webhooks (URL en https), choisissez les événements, et copiez le secret de signature (affiché une fois).

Événements

• case.created

  Un dossier a été créé

• case.resolved

  Un dossier a été soldé (payé)

• invoice.payment_detected

  Paiement détecté sur une facture

• letter.sent

  Un courrier a été validé / envoyé

• letter.tracking_updated

  Le suivi d’un courrier a évolué

• reply.received

  Une réponse a été reçue

Format d’un événement

Le corps ne contient que des références (identifiants) — jamais de donnée personnelle du débiteur. Rappelez l’API avec votre clé pour obtenir le détail.

{
  "id": "d1f2…",            // identifiant de livraison (X-Bleme-Id)
  "type": "invoice.payment_detected",
  "occurred_at": "2026-07-12T09:30:00.000Z",
  "organization_id": "org_…",
  "data": { "case_id": "c_…" }
}

Vérifier la signature

Chaque requête porte les en-têtes X-Bleme-Signature: t=…,v1=…, X-Bleme-Id et X-Bleme-Event. Recalculez le HMAC-SHA256 de la chaîne t + "." + corps_brut avec votre secret, comparez en temps constant, et rejetez au-delà de 5 minutes d’écart.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBleme(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // rejeu
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(parts.v1 ?? "", "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Reprises & fiabilité

Répondez 2xx pour accuser réception. En cas d’échec, BLEME réessaie avec un délai croissant, puis abandonne. La livraison est au moins une fois : dédupliquez sur X-Bleme-Id. Un endpoint qui échoue trop longtemps est désactivé automatiquement (vous êtes prévenu par email). Le bouton Ping de test envoie un événement ping pour valider votre intégration.