Brancher Vimbo sur votre site

Vue d'ensemble

Vous avez déjà un site (Next.js, WordPress, Shopify-like maison, Webflow…). Vimbo lui ajoute une vraie boutique sans que vous ayez à gérer une base de données produits, un panier ou un back-office. Le principe :

• Vous appelez l'API Vimbo avec une clé tenant (mbk_…) pour lister le catalogue.
• Vous affichez les produits avec votre propre design.
• Vous postez la commande — Vimbo recalcule les prix, enregistre la commande, vous renvoie un numéro.
• Le commerçant gère tout depuis le back-office Vimbo (catalogue, stock, commandes).

Vos acheteurs n'ont pas besoin de compte Cimolace : le checkout est invité (un email suffit). Vous gardez votre domaine et votre marque ; Vimbo reste invisible côté client.

Quickstart (5 minutes)

1. Obtenir une clé API

Le commerçant génère une clé storefront depuis son espace Cimolace (ou le staff la crée). Elle ressemble à mbk_votreboutique_xxxxxxxx… et s'envoie en header Authorization: Bearer. La clé identifie le tenant : tous les appels sont automatiquement isolés à votre boutique.

2. Lister le catalogue

curl https://api.cimolace.space/v1/mbolo/storefront/products \
  -H "Authorization: Bearer mbk_votreboutique_xxxxxxxx"

3. Encaisser une commande

Postez le panier ; Vimbo recalcule tout et renvoie la commande.

curl -X POST https://api.cimolace.space/v1/mbolo/storefront/orders \
  -H "Authorization: Bearer mbk_votreboutique_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "email": "client@example.com", "name": "Awa N." },
    "items": [
      { "slug": "equilibre-femme", "variantId": "<id-variante>", "quantity": 1 },
      { "slug": "vitalite-homme", "quantity": 2 }
    ]
  }'

Architecture

Une seule base de données, isolée par tenant. La clé API résout votre tenant_id ; chaque requête est filtrée automatiquement — vous ne voyez jamais le catalogue d'une autre boutique. Trois ressources :

• Catégories — regroupent les produits (optionnel).
• Produits — prix, stock, images, variantes, bénéfices, SEO.
• Commandes — créées au checkout, consultables au back-office.

Base de l'API : https://api.cimolace.space/v1/mbolo/storefront

Authentification

Toutes les requêtes storefront exigent une clé API tenant dans le header Authorization. Préfixe mbk_ pour les clés Vimbo.

Authorization: Bearer mbk_votreboutique_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prix & devises

Tous les montants sont en centimes entiers (price_cents), avec un champ currency (défaut XAF). Pour afficher : divisez par 100. Une variante porte un price_delta_cents qui s'ajoute au prix de base.

Les prix envoyés par le client sont ignorés. Au checkout, Vimbo relit chaque produit/variante en base et recalcule le total — impossible de falsifier un prix côté navigateur.

GET /categories

Liste les catégories actives de votre boutique.

curl https://api.cimolace.space/v1/mbolo/storefront/categories -H "Authorization: Bearer mbk_..."

{
  "data": [
    { "id": "a0…", "slug": "complements", "name": "Compléments", "sort_order": 1 }
  ]
}

GET /products

Liste les produits actifs (les vedettes en premier), images jointes. Filtre optionnel ?category=<id>.

curl "https://api.cimolace.space/v1/mbolo/storefront/products?category=a0…" -H "Authorization: Bearer mbk_..."

{
  "data": [
    {
      "id": "b0…",
      "name": "Équilibre Femme",
      "slug": "equilibre-femme",
      "price_cents": 2990000,
      "compare_at_price_cents": 3490000,
      "currency": "XAF",
      "stock": 50,
      "is_featured": true,
      "tagline": "Harmonie au naturel",
      "benefits": ["100% naturel", "Soutient le cycle"],
      "images": [{ "url": "https://…", "is_primary": true }]
    }
  ]
}

GET /products/:slug

Détail d'un produit par son slug, avec images et variantes.

curl https://api.cimolace.space/v1/mbolo/storefront/products/equilibre-femme -H "Authorization: Bearer mbk_..."

{
  "data": {
    "id": "b0…",
    "name": "Équilibre Femme",
    "price_cents": 2990000,
    "currency": "XAF",
    "benefits": ["100% naturel"],
    "images": [{ "url": "https://…", "is_primary": true }],
    "variants": [
      { "id": "d0…", "label": "Cure 1 mois", "price_delta_cents": 0 },
      { "id": "d1…", "label": "Cure 3 mois", "price_delta_cents": 700000 }
    ]
  }
}

POST /orders — checkout invité

Crée une commande. customer.email est obligatoire ;items référence chaque produit par slug ou productId, avec un variantId optionnel et une quantity.

Corps de requête

{
  "customer": {
    "email": "client@example.com",
    "name": "Awa N.",
    "phone": "+241060000000",
    "address": { "city": "Libreville", "country": "GA" }
  },
  "items": [
    { "slug": "equilibre-femme", "variantId": "d1…", "quantity": 1 },
    { "productId": "b1…", "quantity": 2 }
  ]
}

Réponse

{
  "data": {
    "order": {
      "order_number": "MB-1896-MPTXPO5N",
      "status": "pending",
      "channel": "storefront",
      "total_cents": 9270000,
      "currency": "XAF",
      "customer_email": "client@example.com"
    },
    "items": [ /* lignes recalculées côté serveur */ ],
    "total_cents": 9270000,
    "currency": "XAF"
  }
}

Sécurité

• Clé côté serveur uniquement — jamais dans le bundle navigateur.
• Prix non falsifiables — recalcul systématique en base au checkout.
• Isolation tenant — chaque requête est filtrée par le tenant de la clé.
• Révocation immédiate — une clé compromise se coupe en un clic (401 instantané).
• Paiement — la commande naît en pending. Branchez votre PSP (Stripe, PawaPay…) puis confirmez la commande au back-office / via webhook.

Back-office

Le commerçant gère sa boutique sans toucher au code, depuis l'espace Cimolace :

• Catalogue — créer/éditer produits, catégories, images, variantes, stock, vedettes.
• Commandes — suivre les commandes boutique et storefront, voir le détail des lignes et le client.

Les produits créés au back-office sont immédiatement disponibles via l'API storefront — votre site se met à jour tout seul.

Troubleshooting

Changelog

• Wave 2 — API storefront publique (clé API) + checkout invité.
• Wave 1 — Catalogue riche : catégories, images, variantes, prix barrés, vedettes, bénéfices, SEO.