​

Genuka API — Guide d’intégration e-commerce

Public visé : développeurs front-end / full-stack qui construisent un site e-commerce

pour une entreprise déjà inscrite sur Genuka.

Version d’API : 2023-11 · Préfixe de toutes les routes : /2023-11

​

1. Objectif et périmètre

​

2. Concepts clés

​

2.1 Multi-tenant

Le middleware tenant.scope applique automatiquement les scopes entreprise/boutique sur

les modèles : vous ne « voyez » jamais les données d’une autre entreprise.

​

2.2 Le problème de l’amorçage (bootstrap)

GET /2023-11/company/from-domain?domain=[ma-boutique.com](http://ma-boutique.com)

​

2.3 Entités centrales

• Company — branding, devise par défaut, devises additionnelles, moyens de paiement, config storefront
• Shop — point de vente ; peut porter sa propre devise ; relié à des entrepôts
• Product / ProductVariant — un produit a une ou plusieurs variantes ; le prix et le stock vivent au niveau variante
• Stock (entrepôt) — relié aux boutiques via shop_warehouse
• Customer, Address
• Order — billing (JSON), shipping (JSON), discounts, deliveries, payments, medias
• ShippingFee, PickupLocation, Delivery, DeliveryTracking
• PaymentMethod, Payment
• Collection (catalogue groupé, imbricable) ; Blog / Article / Page (CMS storefront)
• Availability / Unavailability / CalendarEvent (réservation de services par professionnel)
• InboxConversation / Message (chat storefront)

​

3. Parcours storefront de référence

1. Résoudre l’entreprise /company/from-domain) → fixer X-Company
2. Charger les boutiques, choisir une boutique active → fixer X-ShopId
3. Lister les produits / variantes (filtres, pagination)
4. Calculer la disponibilité à partir des champs estimated_quantity* et follow_stock
5. (Optionnel) Authentifier le client — le checkout invité est possible
6. Gérer les adresses du client
7. Vérifier un code promo / charger les promos automatiques
8. Choisir livraison ou retrait
9. Créer la commande POST /customers/orders)
10. Récupérer le lien de paiement (immédiat ou différé)
11. Suivre la commande et la livraison

Panier : Genuka ne stocke pas de panier côté serveur. Le panier est géré par le front

(local/session) jusqu’à la création de la commande.

​

4. Référence des endpoints

​

4.1 Contexte entreprise & boutique

GET /company/from-domain et GET /companies/{company} sont mis en cache 4 semaines

(clés public_company_domain_{domain} / public_company_id_{companyId}). C’est le point

d’amorçage : un seul appel par session suffit.

{

  "collections": [ { "id", "name", "slug", "medias": [...], "sub_collections": [...] } ],

  "minPrice": 1000,

  "maxPrice": 250000,

  "options": { "Couleur": ["Rouge", "Bleu"], "Taille": ["S", "M", "L"] }

}

{

  "id": "<ulid>",

  "name": "Carte bancaire",

  "processor": "stripe",

  "status": true,

  "account_id": null,

  "treasury_account_id": null,

  "metadata": {},

  "configurations": { "publicKey": "pk_live_…" }

}

processor ∈ cash, notchpay, stripe, paydunya, taramoney, pawapay, paypal,

mamoni, flutterwave (enum App\Enum\PaymentMethods). Un type fonctionnel l’accompagne

côté config : card, mobile_money, bank_transfer App\Enum\PaymentMethodType).

Les valeurs secrètes des configurations (clés secretprivatetoken) sont masquées en sortie.

Au checkout, billing.method reprend la valeur processor du moyen choisi (§4.8).

​

4.2 Catalogue produit

​

4.3 Stock & disponibilité

• estimated_quantity — quantité estimée totale (toutes boutiques), ou null si aucune variante ne suit le stock
• estimated_quantity_by_shop — { shop_id: quantité }
• estimated_quantity_by_warehouse — { warehouse_id: quantité }
• stocks — détail par entrepôt (filtré sur la boutique active si X-ShopId)

Le suivi de stock se règle par variante via la colonne *follow_stock**.

Si follow_stock = false, la variante est toujours considérée disponible, quelle que

soit estimated_quantity. Si follow_stock = true, basez la disponibilité sur

estimated_quantity (globale ou par boutique selon X-ShopId).

⚠️ Le stock affiché côté front est indicatif. La disponibilité est **revérifiée au moment

de la création de commande** (voir §4.8). Ne vous fiez jamais au stock client comme source de vérité.

​

4.4 Authentification client

{

  "token": "1|XXXXXXXXXXXXXXXXXXXX",

  "customer": { "id": "...", "first_name": "Jean", "email": "[[email protected]](mailto:[email protected])" }

}

Connecter le client dès le checkout : vous pouvez aussi obtenir un token directement à la

création de commande, sans appel registerlogin séparé — voir le paramètre authenticate en §4.8.

​

4.5 Profil & adresses (client connecté)

​

4.6 Livraison & retrait

{

  "id": "<ulid>", "name": "Livraison Douala", "type": "fixed", "amount": 2000,

  "active": true, "shop_id": "<ulid>", "shop": { },

  "warehouses": [ ], "warehouse_ids": ["<ulid>"], "metadata": {},

  "created_at": "…", "updated_at": "…"

}

type vaut toujours fixed (enum ShippingFeeType) : le amount est un forfait. Le

ciblage géographique se fait par rattachement à des entrepôts warehouse_ids), pas par des

zones tarifaires côté resource. Filtrez les frais pertinents selon la boutique / l’entrepôt active(s).

{

  "address": { "line1": "…", "city": "…", "country": "…", "latitude": 4.05, "longitude": 9.7, "…": "…" },

  "full_address": "Rue 1.234, Douala, CM"

}

Les coordonnées GPS du point de retrait sont dans address.latitude / address.longitude

(utiles pour une carte). Les horaires d’ouverture, s’ils existent, vivent dans metadata /

address.metadata (pas de champ dédié).

• Livraison : shipping.mode = "delivery" + shipping_fee_id
• Retrait : shipping.mode = "pickup" + pickup_location_id

shipping_fee_id et pickup_location_id sont mutuellement exclusifs. Le montant de

livraison est résolu côté serveur depuis le frais ou le point de retrait choisi ; à défaut,

il prend shipping.amount.

​

4.7 Réductions

​

4.8 Création de commande

POST /2023-11/customers/orders

• Fonctionne en checkout invité (l’objet customer crée/retrouve le client) ou connecté Bearer → le client authentifié est utilisé).
• Pilotée par le pipeline UpsertOrderProcess (résolution boutique → client → produits → remises → taxes → livraison → facturation → écriture → médias → notifications).

​

⚠️ Les totaux sont calculés par le serveur

subtotal          = Σ (price × quantity)

out_of_tax_total  = subtotal + shipping − discount

total = net_to_pay = out_of_tax_total + taxes_positives + taxes_negatives

​

Payload recommandé (minimal et correct)

{

  "source": "Genuka Checkout",

  "deferred_payment": true,

  "currency_code": "XAF",

  "customer": {

    "first_name": "Jean",

    "last_name": "Dupont",

    "email": "[[email protected]](mailto:[email protected])",

    "phone": "+237600000000",

    "force": true

  },

  "products": [

    { "product_id": "<product_ulid>", "variant_id": "<variant_ulid>", "quantity": 2, "price": 15000 }

  ],

  "billing": {

    "method": "cash",

    "status": "pending",

    "address_id": "<address_ulid>"

  },

  "shipping": {

    "mode": "delivery",

    "status": "pending",

    "scheduled_at": "2026-05-22T10:00:00Z",

    "address_id": "<address_ulid>"

  },

  "shipping_fee_id": "<shipping_fee_ulid>",

  "discounts": [

    { "discount_id": "<discount_ulid>", "code": "WELCOME10" }

  ],

  "metadata": { "note": "Livrer avant midi" }

}

Dans cet exemple : 2 × 15 000 = 30 000 de produits + le montant du shipping_fee_id.

Le total et le net_to_pay renvoyés intègrent ces frais — pas besoin de les calculer.

• customer.force = true : crée le client même si un email/téléphone proche existe (utile en checkout invité). À false, un conflit lève une erreur.
• billing.method : cash, bank, stripe, paydunya, pawapay, paypal, mamoni, taramoney…
• shipping.mode : delivery, pickup, postal, online, other.
• address_id (existante) ou address (objet { first_name, last_name, line1, city, country, … }) pour billing/shipping.
• Devise résolue dans l’ordre : currency_code (requête) → boutique → entreprise → XAF.
• authenticate (booléen) : si true, un token OAuth est émis pour le client de la commande et renvoyé dans la réponse (voir « Connecter le client au checkout » ci-dessous). Pratique pour authentifier automatiquement un acheteur en checkout invité.

​

Livrer à un tiers (cadeau, destinataire ≠ acheteur)

{

  "customer": {

    "first_name": "Jean", "last_name": "Dupont",

    "email": "[[email protected]](mailto:[email protected])", "phone": "+237600000000", "force": true

  },

  "products": [

    { "product_id": "<product_ulid>", "variant_id": "<variant_ulid>", "quantity": 1, "price": 15000 }

  ],

  "billing": { "method": "cash", "status": "pending" },

  "shipping": {

    "mode": "delivery",

    "status": "pending",

    "is_new": true,

    "address": {

      "first_name": "Marie", "last_name": "Kamga",

      "phone": "+237699999999", "email": "[[email protected]](mailto:[email protected])",

      "line1": "Rue 1.234, Bonapriso", "city": "Douala", "country": "CM"

    }

  },

  "shipping_fee_id": "<shipping_fee_ulid>"

}

1. line1, city, country sont obligatoires dans shipping.address, sinon 400.
2. Mettez "is_new": true* : sinon, pour un client connecté, le serveur réutilise une adresse existante qui matche line1citycountry. is_new force la création d’une nouvelle adresse de livraison.
3. N’utilisez pas un shipping.address_id existant de l’acheteur pour livrer ailleurs : passer un address_id avec un objet address écrase cette adresse. Pour un tiers, envoyez toujours un objet address neuf.
4. L’adresse est enregistrée avec is_shipping = true, is_billing = false. Comme un nom de destinataire est fourni, elle ne devient pas l’adresse primaire de l’acheteur is_primary reste false) — ses propres adresses restent intactes.
5. En retrait mode = "pickup"), aucune adresse n’est requise : seul pickup_location_id compte. Indiquez le destinataire tiers via metadata.note.

​

Réponse

{

  "data": {

    "id": "<order_ulid>",

    "reference": "CMD-000123",

    "amount": 32000,

    "amount_due": 32000,

    "currency": "XAF",

    "billing": { "method": "cash", "status": "pending", "total": 32000, "net_to_pay": 32000, "address": { } },

    "shipping": { "mode": "delivery", "status": "pending", "amount": 2000, "address": { } },

    "products": [ ],

    "discounts": [ ],

    "deliveries": [ ],

    "payments": [ ]

  },

  "payment_link": "[https://checkout.stripe.com/](https://checkout.stripe.com/)..."

}

payment_link* est renseigné automatiquement quand deferred_payment est absent ou

false (paiement immédiat). Si deferred_payment = true, il vaut null et vous générez

le lien plus tard (§4.9).

​

Connecter le client au checkout authenticate)

{

  "data": { "id": "<order_ulid>", "reference": "CMD-000123" },

  "payment_link": null,

  "token": "<oauth_access_token>",

  "customer": { "id": "<customer_ulid>", "first_name": "Jean", "email": "[[email protected]](mailto:[email protected])" }

}

Le token est émis pour le client de la commande (celui résolu/créé par le pipeline). En

checkout connecté (requête déjà porteuse d’un Bearer), authenticate renvoie simplement un

nouveau token pour ce même client.

​

Autres routes commande

​

4.9 Paiement

POST /2023-11/customers/orders/{order}/payments

{ "amount_due": 32000, "success_url": "https://...", "cancel_url": "https://..." }

• amount_due optionnel (défaut : order.amount_due).
• success_url / cancel_url (alias : callback).
• Réponse : 200 { "url": "https://..." }, ou 400 { "message": "Payment link could not be generated" }.

Endpoints provider directs POST /2023-11/{stripe|paydunya|pawapay|mamoni|paypal|taramoney}/checkout)

existent mais sont des détails d’implémentation : passez par payment_link / /payments.

​

4.10 Suivi de livraison

{

  "id": "<ulid>", "tracking_number": "TRK-00123", "tracking_url": "[https://…](https://…)",

  "order_id": "<ulid>", "status": "taken_in_charge", "mode": "default",

  "scheduled_at": "…", "starts_at": null, "ends_at": null,

  "address": { },

  "products": [ { "title": "…", "quantity": 2 } ],

  "delivery_status": { "is_complete": false, "is_partial": true, "delivered_quantity": 1, "sequence": 1, "is_first": true },

  "user": { "totalDeliveries": 12 }

}

status ∈ idle, pending, taken_in_charge, partial_delivery, delivered, cancelled

(enum App\Enum\DeliveryStatus). Une commande peut être livrée en plusieurs fois :

deliveries[] porte chaque tournée, et delivery_status indique l’avancement (quantité livrée,

séquence, livraison partielle).

{

  "delivery": { "id": "<ulid>", "status": "taken_in_charge", "order_id": "<ulid>" },

  "position": { "latitude": 4.0511, "longitude": 9.7679, "accuracy": 10, "heading": 120, "speed": 5.5, "updated_at": "…" }

}

Si aucune position n’a encore été enregistrée : { "message": "Aucune position disponible" }.

Pour un suivi « live », faites du polling sur cet endpoint. Affichez tracking_number,

tracking_url et la position (lat/lng + heading pour orienter une icône sur la carte).

​

4.11 Documents de commande (médias)

{

  "medias": [

    { "src": "[https://exemple.com/facture.pdf](https://exemple.com/facture.pdf)" },

    { "base64": "data:application/pdf;base64,JVBER...", "name": "bon-commande.pdf" },

    { "file": "<fichier uploadé>" },

    { "id": "<media_id_existant>" }

  ]

}

• { "id": "..." } lors d’un PUT conserve un média déjà attaché (les médias absents du tableau sont supprimés).
• Lecture : OrderDetailResource expose medias (publics) et private_medias (signature/privés).

​

4.12 Collections (catalogue groupé)

/collections/{id}/products renvoie des ProductDetailResource complets (prix, variantes,

stock, médias) — c’est l’endpoint à câbler sur une page catégorie. Pour ne lister que les

collections ayant du stock à afficher, ajoutez filter[withProducts]=1.

​

4.13 Contenu éditorial — Blogs, Articles, Pages (CMS)

SEO / rendu : utilisez toujours les routes handle/{slug} pour des URLs propres

/blog/mon-article, /p/a-propos). content est du HTML/markdown éditorial à rendre tel quel ;

medias[] fournit l’image de couverture (champs microthumblargewebp).

​

4.14 Réservation de services — disponibilités & créneaux

{

  "status": true,

  "data": {

    "professional_id": "<ulid>",

    "professional_name": "…",

    "unavailable": false,

    "slots": [

      { "start": "09:00", "end": "09:30", "duration": 30, "buffer": 10, "available": true }

    ]

  }

}

Le moteur part des plages availabilities du jour, découpe en créneaux de

service.duration_minutes espacés de + buffer_minutes, exclut les rendez-vous déjà pris

CalendarEvent), les créneaux passés et ceux qui débordent. Si le jour est marqué indisponible,

unavailable = true et slots = [].

1. unavailabilities/dates → griser les jours bloqués du calendrier.
2. À la sélection d’un jour : availabilities/slots → afficher les créneaux available: true.
3. Le client choisit un créneau, puis vous créez la commande (§4.8) en plaçant l’heure du RDV dans shipping.scheduled_at (et/ou metadata).

​

4.15 Chat storefront (messagerie temps réel)

{ "type": "text", "content": { "body": "Bonjour, ce produit est-il dispo ?" } }

• type requis ; content.body requis si type=text (max 5000 caractères). Les types internes/système sont refusés 403).
• Réponse : la ressource MessageResource créée.
• La liste de messages renvoie aussi un return_link vers le canal d’origine (WhatsApp, Messenger, Instagram, Telegram) quand la conversation y est rattachée.

Ce module est optionnel pour une boutique : utile pour le support / la conversion. Le jeton de

conversation est émis par le widget de chat lors de l’ouverture d’une session.

​

4.16 Factures & documents publics

​

4.17 Plans (hors boutique)

​

5. Multi-devise

• CompanyResource expose currency (devise par défaut) et currencies[] (additionnelles).
• Chaque Shop peut porter sa propre currency_code / currency_name.
• Devise d’une commande résolue : currency_code (requête) → boutique → entreprise → XAF.

1. Afficher la devise active (boutique avant entreprise).
2. Figer les prix transactionnels dans la devise de la commande.
3. Ne jamais reconvertir a posteriori une commande déjà créée.

​

6. Multi-boutique

• Liste des boutiques publiques via /shops.
• Scope via X-ShopId sur catalogue, stock, prix, checkout, suivi.
• Relations boutiques ↔ entrepôts pour le stock.

1. Imposer le choix d’une boutique au début du parcours.
2. Propager X-ShopId partout.
3. Isoler le panier par boutique (devise, stock et prix diffèrent).

​

7. Conventions & gestion des erreurs

• Pagination : enveloppe Laravel { data, links, meta }. Contrôle via per_page ou page[size].
• Filtres/tris/includes : convention Spatie QueryBuilder filter[x], sort, include).
• Idempotence : l’API détecte les doublons CheckDuplicateOrderTask), mais protégez aussi le bouton de paiement côté front (désactivation + clé d’idempotence applicative).

​

8. Checklist e-commerce (à ne pas oublier)

1. Panier persistant (invité + connecté) et fusion à la connexion — géré côté front.
2. Idempotence du POST /customers/orders (anti double-commande).
3. Revérification serveur des prix/stock : ne jamais faire confiance au front (déjà appliqué par le pipeline).
4. Taxes complètes (produits, livraison, remises) — calculées côté serveur, à afficher fidèlement.
5. E-mails transactionnels : confirmation, paiement, expédition, échec.
6. Webhooks / polling pour synchroniser statut commande/paiement/livraison.
7. Remboursements, retours, notes de crédit returns, credit_notes dans OrderDetailResource).
8. SEO catalogue (slug handle, métadonnées, schema.org).
9. Conformité RGPD/PII (rétention, droit à l’effacement).
10. Observabilité (correlation id dans les logs, alertes paiement/webhook).
11. Anti-abus du checkout (rate limit, captcha selon le risque).
12. Tests E2E du parcours complet (catalogue → panier → paiement → suivi).

​

9. Roadmap d’implémentation conseillée

⚠️ La sécurité, l’idempotence et le monitoring (phase 4) ne sont pas optionnels : intégrez-les

au plus tôt plutôt que de les repousser en fin de projet.