Bloomy Stock API

Principes

Quatre règles gouvernent toute l'API. Les comprendre évite 90 % des surprises d'intégration.

Authentification

Chaque requête porte une clé API de boutique.

Authorization: Bearer blm_sk_f20976162e1e4edd59c9_Xj4mPq…

L'en-tête X-Api-Key: blm_sk_… est également accepté pour les ERP qui ne savent pas envoyer d'en-tête Authorization.

Format de la clé

blm_sk_<keyId 20 hex>_<secret 43 caractères base64url>

Seul le SHA-256 de la clé est stocké côté Bloomy. Une clé perdue ne peut pas être retrouvée : il faut la révoquer et en émettre une nouvelle.

Cycle de vie d'une clé

C'est le fleuriste qui crée sa clé lui-même, depuis l'application Bloomy : Réglages boutique → Synchronisation externe → Gérer mes clés API. Aucune intervention de Bloomy n'est nécessaire. Un admin Bloomy peut le faire à sa place en cas de besoin.

Callables (côté application)

Un fleuriste ne peut agir que sur sa propre boutique ; un admin peut passer un floristId pour agir au nom d'une boutique.

Statuts d'une clé

Scopes

Une clé sans le scope requis reçoit 403 insufficient_scope. Pour un ERP qui ne fait que pousser du stock, catalog:read + stock:write suffit.

Le modèle de données : variantId

Le catalogue Bloomy est constitué d'articles — « Rose » — déclinés en variantes de couleur — « Rose Rouge », « Rose Blanche ». Au 16 août 2026 : 116 articles catalogue, 738 variantes adressables.

colorValue est la couleur ARGB 32 bits non signée telle que stockée par Bloomy — 4294198070 vaut #F44336. Le champ colorHex est fourni en plus, pour lisibilité.

Procédure de mapping

Les six étapes, dans l'ordre, d'un premier raccordement jusqu'à la synchronisation continue.

1. Récupérer le catalogue. GET /catalog/variants en paginant jusqu'à pagination.hasMore == false. Stockez variantId, name, type, colorHex, imageUrl.
2. Associer vos références. Ajoutez un champ « ID Bloomy » sur chaque article de votre logiciel. GET /catalog/variants?q=rose+rouge aide à retrouver une variante par nom — recherche insensible à la casse et aux accents.
3. Vérifier le périmètre réel. GET /stock retourne ce que la boutique vend effectivement : items[] sont pilotables tout de suite ; unmappableItems[] sont les articles maison du fleuriste, sans équivalent catalogue, non pilotables ; une variante absente des deux signifie que le fleuriste ne la vend pas encore.
4. Premier envoi. POST /stock/bulk avec l'ensemble des variantes mappées.
5. Synchronisation continue. Rejouez POST /stock/bulk à chaque changement de stock, ou à intervalle régulier — toutes les 15 minutes par exemple.
6. Rafraîchir le catalogue. Comparez catalogVersion, présent dans toutes les réponses catalogue, à celui de votre dernier import. S'il a changé, réimportez. Une variante ajoutée par Bloomy apparaît sous 5 minutes.

Vérifier que ça fonctionne

Dès qu'une clé API est active, l'inventaire Bloomy bascule automatiquement en suivi à la tige : le fleuriste voit la quantité exacte de chaque variante, au lieu du bouton En stock / Épuisé ou des niveaux Faible / Élevé. C'est délibéré, et c'est votre meilleur outil de test.

1. Le fleuriste ouvre Inventaire dans l'application Bloomy.
2. Une bannière indique combien d'articles sont synchronisés et à quand remonte la dernière mise à jour.
3. Vous lancez une synchronisation depuis votre logiciel.
4. Les nombres et l'horodatage changent sous ses yeux, en direct.

Chaque article piloté par l'API porte un badge API ; une info-bulle donne la date de sa dernière synchronisation. Un badge grisé signale un article que votre système n'a jamais alimenté — utile pour repérer un mapping incomplet.

Techniquement, Bloomy écrit stockApiEnabled: true sur boutique/info dès qu'une clé est utilisable, et repasse à false quand la dernière est révoquée.

Endpoints

Toutes les réponses sont en JSON UTF-8 et contiennent un requestId, également renvoyé dans l'en-tête X-Request-Id. Communiquez-le au support Bloomy en cas de problème.

curl -H "Authorization: Bearer $BLOOMY_KEY" \
  https://app.bloomy.one/api/v1/ping

{
  "ok": true,
  "apiVersion": "1.0.0",
  "floristId": "8xKq2mPz",
  "scopes": ["catalog:read", "stock:read", "stock:write"],
  "keyLabel": "Pixelfleurs Prod",
  "serverTime": "2026-08-16T07:39:57.630Z"
}

curl -H "Authorization: Bearer $BLOOMY_KEY" \
  "https://app.bloomy.one/api/v1/catalog/variants?q=rose&limit=2"

{
  "variants": [
    {
      "variantId": "rose",
      "catalogItemId": "rose",
      "svgKey": "rose",
      "name": "Rose",
      "itemName": "Rose",
      "variantName": null,
      "type": "flower",
      "category": "Fleurs",
      "colorValue": null,
      "colorHex": null,
      "imageUrl": "https://firebasestorage.googleapis.com/.../rose.png",
      "isBaseVariant": true
    },
    {
      "variantId": "rose_4294198070",
      "catalogItemId": "rose",
      "svgKey": "rose",
      "name": "Rose Rouge",
      "itemName": "Rose",
      "variantName": "Rouge",
      "type": "flower",
      "category": "Fleurs",
      "colorValue": 4294198070,
      "colorHex": "#F44336",
      "imageUrl": "https://firebasestorage.googleapis.com/.../rose_rouge.png",
      "isBaseVariant": false
    }
  ],
  "pagination": { "total": 3, "offset": 0, "limit": 2, "hasMore": true, "nextOffset": 2 },
  "catalogVersion": "62d4a92dc829bd90",
  "catalogWarnings": [],
  "requestId": "0695abdfa06f1c03"
}

{
  "variant": {
    "variantId": "rose_4294198070",
    "catalogItemId": "rose",
    "svgKey": "rose",
    "name": "Rose Rouge",
    "itemName": "Rose",
    "variantName": "Rouge",
    "type": "flower",
    "category": "Fleurs",
    "colorValue": 4294198070,
    "colorHex": "#F44336",
    "imageUrl": "https://firebasestorage.googleapis.com/.../rose_rouge.png",
    "isBaseVariant": false
  },
  "catalogVersion": "62d4a92dc829bd90",
  "requestId": "1e74037816cadf0a"
}

{
  "floristId": "8xKq2mPz",
  "items": [
    {
      "variantId": "eucalyptus",
      "itemId": "Mk3pL9",
      "name": "Eucalyptus",
      "type": "foliage",
      "colorValue": null,
      "stock": 0,
      "price": 2,
      "available": false,
      "inCatalog": true,
      "lastSyncedAt": null,
      "lastSyncSource": null,
      "externalRef": null,
      "consumedByBloomySinceSync": null
    },
    {
      "variantId": "rose_4294198070",
      "itemId": "Xy7bQ2",
      "name": "Rose Rouge",
      "type": "flower",
      "colorValue": 4294198070,
      "stock": 24,
      "price": 3.5,
      "available": true,
      "inCatalog": true,
      "lastSyncedAt": null,
      "lastSyncSource": null,
      "externalRef": null,
      "consumedByBloomySinceSync": null
    }
  ],
  "unmappableItems": [
    { "itemId": "Zz1cV4", "name": "Vase artisanal", "type": "extra", "stock": 4, "reason": "no_catalog_variant" }
  ],
  "duplicateVariants": [],
  "counts": { "total": 2, "mapped": 2, "available": 1 },
  "catalogVersion": "62d4a92dc829bd90",
  "requestId": "768aa73f32d6ed85"
}

{
  "variantId": "rose_4294198070",
  "itemId": "Xy7bQ2",
  "name": "Rose Rouge",
  "type": "flower",
  "colorValue": 4294198070,
  "stock": 36,
  "price": 3.5,
  "available": true,
  "inCatalog": true,
  "lastSyncedAt": "2026-08-16T07:39:57.634Z",
  "lastSyncSource": "external_api",
  "externalRef": "SYNC-2026-08-16T07:00Z",
  "consumedByBloomySinceSync": 0,
  "requestId": "09de52b3d783592e"
}

curl -X PUT \
  -H "Authorization: Bearer $BLOOMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stock": 36, "reference": "PXF-ROSE-RED-60"}' \
  https://app.bloomy.one/api/v1/stock/rose_4294198070

{
  "variantId": "rose_4294198070",
  "itemId": "Xy7bQ2",
  "stock": 36,
  "previousStock": 24,
  "created": false,
  "warnings": [],
  "syncedAt": "2026-08-16T07:39:57.633Z",
  "requestId": "adb694d716ad13f5"
}

curl -X POST \
  -H "Authorization: Bearer $BLOOMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "reference": "SYNC-2026-08-16T07:00Z",
        "updates": [
          { "variantId": "rose_4294198070", "stock": 36 },
          { "variantId": "eucalyptus",      "stock": 12 },
          { "variantId": "rose_4294967295", "stock": 5  },
          { "variantId": "tulipe_999",      "stock": 3  }
        ]
      }' \
  https://app.bloomy.one/api/v1/stock/bulk

{
  "floristId": "8xKq2mPz",
  "summary": { "received": 4, "updated": 2, "created": 0, "failed": 2, "zeroedByMissingBehaviour": 0 },
  "results": [
    { "variantId": "rose_4294198070", "itemId": "Xy7bQ2", "status": "updated", "stock": 36, "previousStock": 36 },
    { "variantId": "eucalyptus", "itemId": "Mk3pL9", "status": "updated", "stock": 12, "previousStock": 0 },
    {
      "variantId": "rose_4294967295",
      "status": "error",
      "code": "not_in_inventory",
      "message": "Not in this boutique's inventory. Retry with createIfMissing: true to add it."
    },
    {
      "variantId": "tulipe_999",
      "status": "error",
      "code": "variant_not_found",
      "message": "No catalog variant with id 'tulipe_999'."
    }
  ],
  "syncedAt": "2026-08-16T07:39:57.635Z",
  "requestId": "1baf2aacf4bcce63"
}

Erreurs

Format uniforme sur toute l'API.

{
  "error": {
    "code": "variant_not_found",
    "message": "No catalog variant with id 'tulipe_999'.",
    "details": { "variantId": "tulipe_999" }
  },
  "requestId": "1332686604f24974"
}

Limites

Les quotas sont appliqués au mieux, par instance serveur. Le dépassement renvoie 429 avec un en-tête Retry-After en secondes.

Bonnes pratiques

Six réflexes qui font la différence entre une intégration qui tient et une qui dérive.

• Un bulk vaut mieux que N PUT. Un seul appel pour 300 variantes plutôt que 300 appels : plus rapide, et hors quota d'écriture.
• N'envoyez que les changements en régime nominal, et faites une resynchronisation complète — missingBehaviour: "zero" — une fois par jour ou après un incident.
• Gérez la concurrence. Bloomy décrémente le stock quand un fleuriste accepte une commande. Si votre ERP calcule un stock à T0 et l'écrit à T0+5 min, une vente intervenue entre-temps est écrasée. Deux parades : synchroniser toutes les 5 à 15 minutes, ou lire consumedByBloomySinceSync avant d'écrire et le déduire de votre propre stock.
• Renseignez reference avec un identifiant de job : il ressort dans GET /stock et dans les journaux Bloomy, ce qui accélère beaucoup le support.
• Surveillez available. Un article à false malgré du stock indique un prix manquant côté fleuriste — c'est l'alerte la plus utile à remonter dans votre interface.
• Ne codez pas en dur les variantId. Réimportez le catalogue quand catalogVersion change.

Exemple d'intégration

Node.js — import du catalogue puis synchronisation par lots.

const BASE = "https://app.bloomy.one/api/v1";
const KEY = process.env.BLOOMY_API_KEY;

async function bloomy(path, { method = "GET", body } = {}) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) {
    throw new Error(`${json.error.code}: ${json.error.message} (req ${json.requestId})`);
  }
  return json;
}

// 1. Import du catalogue — une fois, puis quand catalogVersion change
async function fetchCatalog() {
  const all = [];
  let offset = 0;
  for (;;) {
    const page = await bloomy(`/catalog/variants?limit=200&offset=${offset}`);
    all.push(...page.variants);
    if (!page.pagination.hasMore) return { variants: all, version: page.catalogVersion };
    offset = page.pagination.nextOffset;
  }
}

// 2. Synchronisation du stock — mapping = { refInterne: variantId }
async function syncStock(mapping, stockParRef) {
  const updates = Object.entries(mapping).map(([ref, variantId]) => ({
    variantId,
    stock: stockParRef[ref] ?? 0,
  }));

  // Découpage en lots de 500
  for (let i = 0; i < updates.length; i += 500) {
    const res = await bloomy("/stock/bulk", {
      method: "POST",
      body: {
        reference: `SYNC-${new Date().toISOString()}`,
        updates: updates.slice(i, i + 500),
      },
    });

    if (res.summary.failed > 0) {
      for (const r of res.results.filter((x) => x.status === "error")) {
        console.error(`[Bloomy] ${r.variantId} → ${r.code}: ${r.message}`);
      }
    }
    console.log(`[Bloomy] ${res.summary.updated} variantes mises à jour`);
  }
}

Support & versioning

• Le numéro de version est renvoyé dans l'en-tête X-Bloomy-Api-Version et dans GET /ping.
• Le chemin /api/v1 est stable : aucun changement cassant n'y sera introduit. Les ajouts de champs en réponse ne sont pas considérés comme cassants — votre parseur doit ignorer les champs inconnus.
• Support : joignez le requestId de la requête concernée.