L'API d'Établis

Votre atelier sur votre propre site : votre fiche, vos prestations et vos prix, les instruments et pièces de votre boutique, et un formulaire de demande qui arrive directement dans Établis. Vous gérez tout dans Établis, votre site suit.

À quoi elle sert

• Fiche de l'atelier (portée « atelier ») : nom, adresse, téléphone, logo et présentation.
• Prestations et prix (portée « prestations ») : vos prestations, avec leurs prix si votre site les affiche.
• Catalogue de la boutique (portée « catalogue ») : les articles publiés, avec photos et prix.
• Demandes des visiteurs (portée « demandes ») : un formulaire de votre site qui arrive dans votre boutique.

L'API ne montre que ce que votre site Établis montre déjà à tout le monde. Elle ne donne jamais accès à vos clients, à vos dépôts, à vos devis ni à vos factures, et chaque clé ne voit que son propre atelier.

Obtenir l'accès

1. Votre atelier est en offre Magasin & série.
2. Le gérant fait la demande dans Réglages → Accès API : l'adresse du site où l'API servira, ce que vous voulez en faire, et l'accord sur les règles.
3. L'équipe d'Établis lit la demande et répond dans l'application. Cette étape évite qu'on se serve de l'API pour imiter Établis.
4. Une fois l'accès ouvert, le gérant crée ses clés (5 actives au plus), une par site ou par usage.

S'authentifier

Chaque appel porte une clé dans l'en-tête Authorization (ou, si votre outil ne permet pas de le régler, dans X-Api-Key). Une clé commence par etb_live_, suivie de 32 lettres et chiffres. Elle ne s'affiche qu'une fois, à sa création : Établis n'en garde qu'une empreinte.

Authorization: Bearer etb_live_…

Toutes les adresses commencent par :

https://etablis.fr/api/v1

Depuis votre serveur (le plus sûr) : la clé reste secrète, rangée dans une variable d'environnement, jamais dans le code de vos pages. Depuis un navigateur : la clé se voit dans la page, alors elle ne marche que depuis les domaines déclarés sur la clé (voir plus bas).

Les points d'accès

Les réponses sont en JSON (UTF-8). Des champs peuvent s'ajouter avec le temps : ignorez ceux que vous ne connaissez pas.

GET/api/v1/atelierportée « atelier »

La fiche publique de votre atelier. Les adresses d'images sont complètes ; les champs non renseignés valent null.

curl https://etablis.fr/api/v1/atelier \
  -H "Authorization: Bearer $ETABLIS_API_KEY"

const API = "https://etablis.fr/api/v1";
const headers = { Authorization: `Bearer ${process.env.ETABLIS_API_KEY}` };

const { atelier } = await fetch(`${API}/atelier`, { headers }).then((r) => r.json());

{
  "atelier": {
    "name": "Lutherie Martin",
    "city": "Lyon",
    "address": "12 rue des Luthiers, 69001 Lyon",
    "phone": "04 78 00 00 00",
    "email": "bonjour@lutherie-martin.fr",
    "logoUrl": "https://etablis.fr/uploads/cm1k…/logo.png",
    "brandColor": "#B5552F",
    "siteUrl": "https://etablis.fr/atelier/lutherie-martin",
    "intro": "Réglages, refrettes et électronique pour guitares et basses, depuis 2011."
  }
}

GET/api/v1/prestationsportée « prestations »

Vos prestations actives, dans l'ordre de votre catalogue. Le prix suit votre réglage « Afficher mes prix sur le site » : quand il est décoché, price vaut null et pricesVisible false.

curl https://etablis.fr/api/v1/prestations \
  -H "Authorization: Bearer $ETABLIS_API_KEY"

{
  "prestations": [
    {
      "id": "cm1r2…",
      "name": "Réglage complet",
      "category": "Réglage",
      "price": 85
    },
    {
      "id": "cm1r3…",
      "name": "Refrettage inox",
      "category": "Frettes",
      "price": 420
    }
  ],
  "pricesVisible": true,
  "currency": "EUR"
}

GET/api/v1/catalogueportée « catalogue »

Les articles que votre site montre : publiés, pas en brouillon, et les articles vendus pendant 30 jours (marqués VENDU). Prix en euros TTC, entiers. Le prix de vente réel et l'acheteur ne sont jamais donnés.

curl "https://etablis.fr/api/v1/catalogue?kind=INSTRUMENT&status=EN_VENTE&limit=1" \
  -H "Authorization: Bearer $ETABLIS_API_KEY"

{
  "articles": [
    {
      "id": "cm1q8w2e3r4t5y6u7i8o9p0a",
      "title": "Fender Stratocaster 1978",
      "kind": "INSTRUMENT",
      "kindLabel": "Instrument",
      "category": "Électrique",
      "brand": "Fender",
      "model": "Stratocaster",
      "year": "1978",
      "condition": "VINTAGE",
      "conditionLabel": "Vintage",
      "description": "Micros d'origine, frettes refaites à l'atelier.",
      "price": 2450,
      "currency": "EUR",
      "status": "EN_VENTE",
      "statusLabel": "En vente",
      "quantity": 1,
      "photos": [
        "https://etablis.fr/uploads/cm1k…/boutique-1.jpg"
      ],
      "specs": [
        {
          "label": "Manche",
          "value": "Érable, touche palissandre"
        },
        {
          "label": "Poids",
          "value": "3,9 kg"
        }
      ],
      "url": "https://etablis.fr/atelier/lutherie-martin/catalogue/cm1q8w2e3r4t5y6u7i8o9p0a",
      "soldAt": null,
      "createdAt": "2026-09-12T09:30:00.000Z",
      "updatedAt": "2026-09-20T16:05:00.000Z"
    }
  ],
  "total": 14,
  "limit": 1,
  "offset": 0
}

GET/api/v1/catalogue/{id}portée « catalogue »

Un article, s'il est visible sur votre site ; sinon 404 (code introuvable).

curl https://etablis.fr/api/v1/catalogue/cm1q8w2e3r4t5y6u7i8o9p0a \
  -H "Authorization: Bearer $ETABLIS_API_KEY"

{ "article": { "id": "cm1q8w2e3r4t5y6u7i8o9p0a", "title": "Fender Stratocaster 1978", … } }

POST/api/v1/demandesportée « demandes »

La demande d'un visiteur de votre site (un article qui l'intéresse, une question). Elle arrive dans Établis, Boutique → « Demandes à traiter », et votre équipe est prévenue. Répondez-lui ensuite par e-mail ou par téléphone.

curl https://etablis.fr/api/v1/demandes \
  -H "Authorization: Bearer $ETABLIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Camille Durand","email":"camille@example.com","message":"La Stratocaster est-elle toujours disponible ? Je peux passer samedi.","itemId":"cm1q8w2e3r4t5y6u7i8o9p0a"}'

const reponse = await fetch("https://etablis.fr/api/v1/demandes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ETABLIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name, email, phone, message, itemId, website: champCache }),
});
if (reponse.status === 429) {
  // Trop de demandes : réessayer après reponse.headers.get("Retry-After") secondes.
}
const resultat = await reponse.json(); // { ok, message, demande } ou { error, code, errors }

{
  "ok": true,
  "message": "Demande transmise à l'atelier.",
  "demande": {
    "id": "cm1z9…",
    "createdAt": "2026-09-25T10:12:00.000Z"
  }
}

Le même message envoyé deux fois en dix minutes (double clic, page rechargée) ne fait qu'une demande : la réponse est alors 200, avec la demande déjà reçue.

Depuis un navigateur

Pour appeler l'API depuis les pages de votre site, déclarez ses domaines sur la clé (Réglages → Accès API → Créer une clé) : lutherie-martin.fr autorise https://lutherie-martin.fr et https://www.lutherie-martin.fr, pas les autres sous-domaines. Les domaines possibles sont ceux des sites acceptés et leurs sous-domaines ; localhost (en http) sert à vos essais. Un appel depuis un autre domaine reçoit 403 (code domaine_refuse), et une clé sans domaine ne marche que depuis un serveur.

Donnez à une clé de navigateur le moins d'usages possible (par exemple le catalogue seul), et gardez les demandes côté serveur si vous le pouvez.

const reponse = await fetch("https://etablis.fr/api/v1/catalogue?status=EN_VENTE", {
  headers: { Authorization: "Bearer etb_live_…" },
});
const { articles } = await reponse.json();

Les erreurs

Une erreur répond toujours en JSON, avec une phrase en français et un code stable pour votre programme : { "error": "…", "code": "…" }. Pour 422, errors donne le problème champ par champ.

• 400 · json_invalide, parametre_invalide : Corps JSON illisible, filtre ou nombre hors des valeurs permises.
• 401 · cle_manquante, cle_invalide, cle_revoquee : Pas de clé, clé inconnue, ou clé révoquée.
• 403 · domaine_refuse : Appel depuis un navigateur, sur un domaine que la clé n'autorise pas.
• 403 · portee : La clé n'a pas cet usage (par exemple « demandes »).
• 403 · acces_ferme, offre, abonnement_arrete, demonstration : L'accès de l'atelier est fermé, il n'est plus en offre Magasin & série, son abonnement est arrêté, ou c'est une démonstration.
• 404 · introuvable : Article inconnu, ou retiré du catalogue.
• 413 · trop_long : Corps de requête au-delà de 16 Ko.
• 422 · donnees_invalides : Un champ ne va pas : le détail est dans errors, champ par champ.
• 429 · limite_atteinte, trop_d_essais : Trop d'appels : attendez le nombre de secondes de l'en-tête Retry-After.
• 500 · erreur_interne : Un souci de notre côté : réessayez un peu plus tard.

{
  "error": "Vérifiez la demande.",
  "code": "donnees_invalides",
  "errors": {
    "email": "Adresse e-mail invalide"
  }
}

Les limites

• 300 appels par minute et 6 000 par heure, pour chaque clé.
• Clé déclarée pour des domaines (utilisée depuis un navigateur) : chaque visiteur a sa part, 60 appels par minute et 600 par heure. Quelqu'un qui recopie la clé ne peut donc pas épuiser celles de votre site.
• Demandes : 50 par heure pour chaque clé ; avec une clé de navigateur, 5 par heure pour chaque visiteur.
• 5 clés actives par atelier, 10 domaines par clé.
• Au-delà, la réponse est 429 avec l'en-tête Retry-After (en secondes).
• Le navigateur du visiteur garde une lecture une minute (Cache-Control: private, max-age=60). Côté serveur, gardez les réponses quelques minutes : votre site sera plus rapide et loin des limites.

Les règles

En demandant l'accès, le gérant les accepte ; elles font partie des conditions générales (article 11 bis).

• Pour votre atelier seulement : les informations de votre atelier, sur vos propres sites.
• Ni revente, ni marque blanche : pas de service tiré d'Établis proposé à d'autres ateliers ou à d'autres entreprises.
• Ne pas imiter Établis : ni son nom, ni son logo, ni son apparence, et ne jamais se présenter comme Établis. Citer Établis n'est pas obligatoire.
• Rien d'autre que votre atelier : ne pas chercher à lire les données d'autres ateliers, ni à contourner les limites.
• Des clés secrètes : vous répondez de leur usage. Une clé divulguée se révoque aussitôt dans Réglages → Accès API.
• Un accès qui peut se refermer : Établis peut refuser une demande, révoquer une clé ou retirer l'accès à tout moment, sans indemnité.

Une question ?

Écrivez à bonjour@etablis.fr avec le nom de votre atelier : une vraie personne vous répond.