KÒR Connect / DocumentationMa boutique

    Guide 03 · Développeurs

    Intégrer KÒR Connect dans votre site.

    Votre site garde son design. KÒR gère les produits, les prix, le stock vendable et les commandes. Le navigateur lit le catalogue public et envoie les commandes Commerce V2 ; une clé secrète ne sert qu'à votre serveur.

    Adresse d'API actuellement sélectionnée : https://api.korflow.space/functions/v1. Elle est pilotée par KÒR Admin ; les adresses précédentes peuvent rester en alias pendant une migration.

    Priorité : site Bettyna Cosmetics

    1. 1

      Récupérer le slug de la boutique

      Dans l'espace Connect : kor- suivi de 12 caractères hexadécimaux. Il remplace KOR_SHOP_SLUG partout.

    2. 2

      Afficher le catalogue (onglet 1)

      Fichier src/lib/kor-connect.ts + composant Catalogue. Photos, prix et disponibilité viennent de KÒR Marchand.

    3. 3

      Faire valider l'origine HTTPS du site

      Le checkout n'est accepté que depuis une origine HTTPS autorisée par KÒR. Cette activation n'est pas encore en self-service : demandez la validation avant d'ouvrir la commande.

    4. 4

      Installer Turnstile et le formulaire de commande (onglet 2)

      Clé de site publique dans le navigateur ; le jeton obtenu est envoyé dans challenge_token. Jamais de secret Turnstile côté navigateur.

    5. 5

      Passer une commande sentinelle et la suivre (onglet 3)

      Vérifier qu'elle apparaît dans KÒR Marchand, puis la remise, le paiement et le stock. Ce test E2E est encore À CONFIRMER.

    Lecture ≠ écriture. Le catalogue se lit par polling (cache public de 30 s, pas de push temps réel). La commande est une écriture contrôlée par le serveur KÒR : prix, stock et idempotence sont revérifiés. Une commande réserve le stock vendable ; le stock physique est déduit après paiement / remise confirmés dans KÒR Marchand. Commande ≠ encaissement : le paiement en ligne n'est pas garanti.

    Les valeurs surlignées sont à remplacer : KOR_SHOP_SLUG (kor- + 12 caractères hexadécimaux, visible dans votre espace Connect), https://www.votre-site.com (origine HTTPS autorisée), TURNSTILE_SITE_KEY (clé de site publique), les identifiants / prix lus dans l'API et VOTRE_CLE_PRIVEE (clé privée côté serveur uniquement).

    Étape 1 — Client catalogue (sans clé)

    Fichier de destination : src/lib/kor-connect.ts (React / Next.js / Vite). Endpoint public kor-connect-storefront-v1.

    src/lib/kor-connect.ts
    // Navigateur autorisé : aucune clé secrète ici.
    export const shopSlug = "KOR_SHOP_SLUG"; // remplacer uniquement la valeur entre guillemets
    const STOREFRONT = "https://api.korflow.space/functions/v1/kor-connect-storefront-v1";
    
    export type KorProduct = {
      id: string; name: string; description: string | null;
      price_xof: number; discounted_price_xof: number | null;
      image_urls: string[]; available_quantity: number | null;
      web_purchase_supported: boolean;
    };
    
    export async function getShop() {
      const r = await fetch(`${STOREFRONT}/v1/shops/${shopSlug}`);
      if (!r.ok) throw new Error("KÒR boutique: " + r.status);
      return r.json();
    }
    
    export async function getProducts(page = 1, limit = 20) {
      const r = await fetch(`${STOREFRONT}/v1/shops/${shopSlug}/products?page=${page}&limit=${limit}`);
      if (!r.ok) throw new Error("KÒR catalogue: " + r.status);
      const body = await r.json();
      if (body.code !== "kor_connect_products") throw new Error("Réponse inattendue");
      return body as { shop: unknown; data: KorProduct[]; pagination: unknown };
    }
    
    export async function getProduct(id: string) {
      const r = await fetch(`${STOREFRONT}/v1/shops/${shopSlug}/products/${id}`);
      if (!r.ok) throw new Error("KÒR produit: " + r.status);
      return r.json();
    }
    

    Forme de la réponse catalogue

    GET /v1/shops/{slug}/products?page=1&limit=20
    {
      "code": "kor_connect_products",
      "shop": { "...": "infos publiques de la boutique" },
      "data": [{
        "id": "LISTING_ID",
        "name": "Sérum éclat",
        "description": "…",
        "price_xof": 12000,
        "discounted_price_xof": null,
        "image_urls": ["https://…"],
        "available_quantity": 8,
        "web_purchase_supported": true
      }],
      "pagination": { "page": 1, "limit": 20 }
    }

    Étape 2 — Afficher les produits

    Fichier : src/components/Catalogue.tsx. Le bouton ouvre le formulaire OrderForm lorsque le produit est achetable ; il est désactivé quand web_purchase_supported est faux (les promotions ne sont pas encore achetables en V2).

    src/components/Catalogue.tsx
    import { useEffect, useState } from "react";
    import { getProducts, type KorProduct } from "@/lib/kor-connect";
    import { OrderForm } from "./OrderForm";
    
    export function Catalogue() {
      const [items, setItems] = useState<KorProduct[]>([]);
      const [selected, setSelected] = useState<KorProduct | null>(null);
      useEffect(() => {
        const load = () => getProducts().then(r => setItems(r.data)).catch(console.error);
        load();
        const t = setInterval(load, 60_000); // polling : pas de push temps réel
        return () => clearInterval(t);
      }, []);
      return <><ul>{items.map(p => (
        <li key={p.id}>
          {p.image_urls[0] && <img src={p.image_urls[0]} alt={p.name} />}
          <h3>{p.name}</h3>
          <p>{(p.discounted_price_xof ?? p.price_xof).toLocaleString("fr-FR")} FCFA</p>
          <button type="button" onClick={() => setSelected(p)} disabled={!p.web_purchase_supported || (p.available_quantity ?? 0) < 1}>
            {p.web_purchase_supported ? "Commander" : "Disponible en boutique"}
          </button>
        </li>))}</ul>
        {selected && <OrderForm product={selected} />}
      </>;
    }

    WordPress (lecture seule)

    WordPress › bloc HTML personnalisé
    <!-- WordPress : bloc « HTML personnalisé » (catalogue public, lecture seule) -->
    <div id="kor-catalogue"></div>
    <script>
    fetch("https://api.korflow.space/functions/v1/kor-connect-storefront-v1/v1/shops/KOR_SHOP_SLUG/products?page=1&limit=20")
      .then(r => { if (!r.ok) throw new Error("Catalogue indisponible"); return r.json(); })
      .then(({ code, data }) => {
        if (code !== "kor_connect_products" || !Array.isArray(data)) throw new Error("Réponse inattendue");
        const list = document.getElementById("kor-catalogue");
        list.replaceChildren();
        for (const p of data) {
          const card = document.createElement("article");
          const title = document.createElement("h3");
          title.textContent = String(p.name ?? "");
          card.append(title);
          const picture = p.image_urls?.[0];
          if (typeof picture === "string") {
            try {
              const u = new URL(picture);
              if (u.protocol === "https:") {
                const img = document.createElement("img");
                img.src = u.href; img.alt = String(p.name ?? "");
                card.prepend(img);
              }
            } catch { /* image invalide */ }
          }
          const price = document.createElement("p");
          const amount = p.discounted_price_xof ?? p.price_xof;
          price.textContent = Number.isSafeInteger(amount) ? amount.toLocaleString("fr-FR") + " FCFA" : "Prix indisponible";
          card.append(price); list.append(card);
        }
      })
      .catch(() => { document.getElementById("kor-catalogue").textContent = "Catalogue indisponible."; });
    </script>
    Règle de sécurité : jamais de clé kor_sk_..., de secret Turnstile ni de clé service dans une page HTML, une app mobile, une requête client, des logs publics ou un dépôt Git. Révoquez immédiatement toute clé exposée depuis l'espace Connect. État de chaque module : statut des services.