Branchez la simulation
sur votre logiciel

Démarrer en cinq minutes

Une simulation se lance en un appel. La réponse est un 202 : le rendu n'est pas prêt, il arrivera dans la minute.

curl -X POST https://menuiserieai.fr/api/v1/simulations \
  -H "Authorization: Bearer mai_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "portail",
    "site_photo_url": "https://votre-domaine.fr/photo.jpg",
    "material": "aluminium",
    "color": "gris-anthracite",
    "numero_devis": "DEV-2026-118"
  }'

# → 202 { "id": "job_cbae…", "status": "pending" }

Puis suivez l'avancement, toutes les 5 à 10 secondes :

curl https://menuiserieai.fr/api/v1/jobs/job_cbae… \
  -H "Authorization: Bearer mai_live_…"

# → { "status": "succeeded", "simulation_id": "sim_…" }
# Lisez ensuite GET /v1/simulations/sim_… pour l'adresse du rendu.

Le parcours complet

Ce qu'un devis produit, du clic de votre commercial au rendu affiché chez vous. En Node ; la transposition dans un autre langage est directe.

const MAI = 'https://menuiserieai.fr/api/v1';
const H = {
  Authorization: `Bearer ${process.env.MAI_KEY}`,
  'Content-Type': 'application/json',
  // Le commercial à qui la simulation sera imputée.
  'X-MAI-On-Behalf-Of': 'jean.martin@votre-reseau.fr',
};

// ① Lancer. La clé d'idempotence protège d'un double débit sur relance.
const job = await fetch(`${MAI}/simulations`, {
  method: 'POST',
  headers: { ...H, 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    category: 'portail',
    site_photo_url: 'https://votre-domaine.fr/chantier.jpg',
    material: 'aluminium',
    color: 'gris-anthracite',
    numero_devis: 'DEV-2026-118',
    external_ref: 'crm:devis:118',   // votre identifiant, republié tel quel
  }),
}).then((r) => r.json());

// ② Attendre. Le webhook est préférable ; le sondage reste le repli.
let etat = job;
while (etat.status === 'pending' || etat.status === 'processing') {
  await new Promise((r) => setTimeout(r, 5000));   // 5 s, pas moins
  etat = await fetch(`${MAI}/jobs/${job.id}`, { headers: H })
    .then((r) => r.json());
}

if (etat.status === 'failed') {
  // Le crédit n'a PAS été débité : une génération échouée ne coûte rien.
  throw new Error(etat.error?.code ?? 'echec');
}

// ③ Lire le rendu. Le détail publie des champs absents de la liste.
const simulation = await fetch(`${MAI}/simulations/${etat.simulation_id}`, {
  headers: H,
}).then((r) => r.json());

console.log(simulation.generated_image_url);   // à afficher dans votre devis

Authentification

Une clé, un en-tête. Rien d'autre.

Authorization: Bearer mai_live_78ac4b4c755c_…

La clé porte une portée — ce qu'elle peut faire — et un périmètre — ce qu'elle peut voir. Une clé d'agence ne verra jamais les dossiers d'une autre agence, quoi qu'elle demande. Ce n'est pas un filtre que vous appliquez : c'est une contrainte que nous appliquons.

Imputer au bon commercial

Une clé appartient à un compte, pas à une personne. Pour qu'une simulation soit attribuée au commercial qui l'a lancée — et non au siège — indiquez son adresse :

X-MAI-On-Behalf-Of: jean.martin@votre-reseau.fr

L'adresse doit correspondre à celle d'un membre de l'organisation. Elle n'est jamais déclarée : elle est vérifiée. Une adresse inconnue reçoit un ACTOR_NOT_IN_ORGANIZATION, jamais un rattachement approximatif.

Cet en-tête exige la portée act_on_behalf et une autorisation explicite sur la clé — deux verrous, parce qu'imputer une consommation à quelqu'un d'autre n'est pas anodin.

Recevoir les rendus (webhooks)

Plutôt que d'interroger en boucle, laissez-nous vous prévenir. Nous poussons un événement vers l'adresse HTTPS de votre choix, dès que le rendu est prêt.

Les événements

Ce que vous recevez

POST https://votre-domaine.fr/hooks/menuiserieai
X-MAI-Event-Type: simulation.succeeded
X-MAI-Event-Id: evt_9f2a…              ← pour dédupliquer
X-MAI-Signature: t=1785312045,v1=8c1f…  ← à vérifier, voir plus bas
X-MAI-Delivery-Attempt: 1

{
  "id": "evt_9f2a…",
  "type": "simulation.succeeded",
  "created_at": "2026-09-02T09:14:05Z",
  "data": {
    "simulation_id": "sim_…",
    "job_id": "job_…",
    "external_ref": "crm:devis:118",
    "numero_devis": "DEV-2026-118",
    "generated_image_url": "https://…"
  }
}

Vérifier la signature

Obligatoire. Sans cette vérification, n'importe qui connaissant votre adresse peut vous injecter de faux rendus. Le format est celui de Stripe — vos bibliothèques existantes s'appliquent.

import { createHmac, timingSafeEqual } from 'crypto';

function verifier(rawBody, entete, secret) {
  const parts = Object.fromEntries(
    entete.split(',').map((p) => p.split('=')),
  );
  const t = parts.t;

  // ① Rejouer une requête vieille de plusieurs heures ne doit pas passer.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  // ② La signature porte sur « horodatage.corps », corps BRUT — pas
  //    re-sérialisé : un JSON.parse suivi d'un JSON.stringify change les
  //    octets, et la signature ne correspondra plus.
  const attendu = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  // ③ Comparaison en temps constant : une comparaison naïve laisse
  //    deviner la signature octet par octet.
  const a = Buffer.from(attendu);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

L'adresse de réception et le secret se configurent avec votre clé : demandez-les en même temps.

Les routes

12 opérations, engendrées depuis le code. Si une route figure ici, elle existe.

Ouvrir nos écrans chez vous

Plutôt que de reproduire notre interface, ouvrez-la. Un appel renvoie une adresse : votre utilisateur y voit l'écran réel de MenuiserieAI, sans se reconnecter, avec son devis déjà rempli.

curl -X POST https://menuiserieai.fr/api/v1/embed_sessions \
  -H "Authorization: Bearer mai_live_…" \
  -H "X-MAI-On-Behalf-Of: jean.martin@votre-reseau.fr" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "simulate", "quote_ref": "DEV-2026-118" }'

# → 201 { "url": "https://menuiserieai.fr/embed/simulate#…", "expires_in": 1800 }
# Ouvrez cette adresse dans un onglet. Usage unique.

Quinze écrans sont ouvrables : l'assistant de simulation, le studio conversationnel, la bibliothèque, les vidéos, le catalogue, les outils de retouche. La liste est fermée — un chemin libre serait refusé, faute de quoi cette adresse deviendrait une redirection ouverte vers n'importe quelle page authentifiée.

Codes d’erreur

Branchez-vous sur le code, jamais sur le message : le premier est stable, le second peut être reformulé. La colonne Rejouable dit si réessayer a une chance d'aboutir — sur un QUOTA_EXCEEDED, une boucle de reprise ne fera qu'user votre journal.

Portées

Demandez la portée minimale. Une clé qui ne fait que lire ne pourra jamais consommer un crédit, même exploitée.

Les pièges à éviter

Une question ?

Chaque réponse d'erreur porte un request_id. Citez-le : il nous permet de retrouver l'appel exact, sans avoir à vous demander de reproduire le problème.