API & Webhooks

Intégrez les demandes et leads de votre simulateur Hi-Perf dans votre CRM, n8n, Zapier ou backend custom. Disponible à partir du plan Pro.

1. Quick start (60 sec)

1. Allez dans Paramètres → Clés API et générez une clé. Copiez-la (elle ne sera plus jamais affichée).
2. Listez vos demandes :

curl -H "Authorization: Bearer tk_live_xxx" \
     https://simulateur.hi-perf.fr/api/v1/requests?status=new

3. Pour recevoir les nouvelles demandes en temps réel, ajoutez un webhook dans Paramètres → Webhooks.

2. Authentification

Toutes les requêtes API utilisent un header Authorization: Bearer <clé>. Une clé révoquée renvoie une 401 invalid_key. Un tenant sur un plan inférieur à Pro renvoie une 402 plan_required.

Authorization: Bearer tk_live_a3f9c2b1...

Format de la clé : tk_<env>_<32 chars hex> où env est live (prod) ou test (dev). La clé est hashée en SHA-256 côté serveur ; nous n'en stockons jamais la version en clair.

3. Endpoints REST

Base URL : https://simulateur.hi-perf.fr/api/v1. Toutes les réponses sont au format JSON et UTF-8.

GET /v1/requests

Liste paginée des demandes de devis de votre tenant.

curl -H "Authorization: Bearer tk_live_xxx" \
  "https://simulateur.hi-perf.fr/api/v1/requests?status=new&limit=10"

Réponse :

{
  "data": [
    {
      "id": "8f7c1b2e-…",
      "visitor": {
        "first_name": "Marie",
        "last_name":  "Dupont",
        "email":      "marie@…",
        "phone":      "+33 6 12 34 56 78"
      },
      "message":      "Bonjour, je suis intéressée par…",
      "tile":         { "reference": "PAP-001", "name": "Rayures beiges" },
      "surface_type": "wall",
      "status":       "new",
      "internal_notes": null,
      "room_image_url":     "https://….supabase.co/storage/…/room.jpg",
      "generated_image_url":"https://….supabase.co/storage/…/render.jpg",
      "created_at":   "2026-05-17T08:34:12Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 42, "has_more": true }
}

GET /v1/requests/:id

Détail d'une demande spécifique. Renvoie 404 si l'id n'existe pas dans votre tenant.

GET /v1/leads

Liste paginée des leads (formulaire intermédiaire avant la génération). Mêmes paramètres que /v1/requests.

GET /v1/leads/:id

Détail d'un lead.

GET /v1/me

Infos sur votre tenant (plan, crédits restants, date de renouvellement).

{
  "data": {
    "id":   "c6d3…",
    "name": "Cervos Tapisseries",
    "slug": "cervos",
    "plan": {
      "tier":                   "pro",
      "display_name":           "Pro",
      "monthly_projects_quota": 200,
      "projects_remaining":     147,
      "renews_at":              "2026-06-12T17:15:57Z"
    }
  }
}

4. Webhooks

Configurez une URL HTTPS de votre backend dans Paramètres → Webhooks. Hi-Perf y enverra un POST JSON signé HMAC à chaque événement souscrit.

Événements disponibles

Payload

POST https://votre-backend.com/webhooks/hi-perf
Content-Type:        application/json
User-Agent:          HiPerf-Webhook/1.0
X-HiPerf-Timestamp:  1747556052
X-HiPerf-Signature:  v1=4f8a3e6b9c2d…

{
  "event":      "request.created",
  "created_at": "2026-05-17T08:34:12Z",
  "data": {
    "id": "8f7c1b2e-…",
    "visitor": { "first_name": "Marie", … },
    "tile":    { "reference": "PAP-001", … },
    "created_at": "2026-05-17T08:34:12Z"
  }
}

Vérifier la signature

Vérifiez chaque webhook reçu pour vous assurer qu'il vient bien de Hi-Perf (et pas d'un attaquant). Signature = HMAC-SHA256(secret, "{timestamp}.{body}"), en hex.

Node.js :

import crypto from "node:crypto";

function verifyHiPerfSignature(secret, headers, rawBody) {
  const ts  = headers["x-hiperf-timestamp"];
  const sig = headers["x-hiperf-signature"];                  // "v1=4f8a…"
  const provided = (sig.match(/v1=([a-f0-9]+)/) || [])[1];
  if (!ts || !provided) return false;

  // Anti-replay : 5 minutes de tolérance
  if (Math.abs(Date.now()/1000 - parseInt(ts)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(provided, "hex"),
  );
}

Python :

import hmac, hashlib, time

def verify_hi_perf_signature(secret, headers, raw_body):
    ts  = headers.get("x-hiperf-timestamp")
    sig = headers.get("x-hiperf-signature", "")
    provided = sig.split("v1=")[-1] if "v1=" in sig else ""
    if not ts or not provided: return False
    if abs(time.time() - int(ts)) > 300: return False
    expected = hmac.new(secret.encode(),
                        f"{ts}.{raw_body}".encode(),
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, provided)

Retries

Si votre serveur répond autre chose qu'un 2xx (ou ne répond pas dans 15 s), Hi-Perf retry 3 fois avec backoff exponentiel : 1 min, 5 min, 30 min. Après 4 tentatives échouées, la livraison est marquée exhausted et abandonnée.

Idempotence : votre handler peut être appelé plusieurs fois pour le même event en cas de retry réussi après timeout côté Hi-Perf. Utilisez data.id + event comme clé d'idempotence côté backend.

5. Codes d'erreur

Format des erreurs :

{
  "error": {
    "code":    "plan_required",
    "message": "L'API n'est disponible qu'à partir du plan Pro. Plan actuel : essai.",
    "upgrade_url": "/admin/billing"
  }
}

6. Rate limits

V1 : pas de rate limit dédié à l'API. Les routes partagent le throttle in-memory global de l'app (généreux, ~100 req/min/IP). V2 : limite par clé API. Pour des besoins de volume élevé, contactez mc@hi-perf.fr.

Une question ? Un bug ? Écrivez à mc@hi-perf.fr.
Hi-Perf SAS. CGV · Confidentialité · Mentions légales