Kora OS

Documentation API

Dernière mise à jour : Juillet 2026

L'API Kora OS permet de connecter un site externe (WooCommerce, PrestaShop, site sur-mesure) à votre compte : récupérer le catalogue produits, créer des commandes, et encaisser des paiements mobile money via DigitalPaye. Une seule clé API couvre toutes vos boutiques — chaque requête précise ensuite la boutique visée.

1. Créer une clé API

Depuis le menu principal : Développeur → Accès API → Nouvelle clé. Choisissez les permissions nécessaires (lecture produits, écriture produits, création de commandes, encaissement). La clé complète n'est affichée qu'une seule fois — conservez-la en lieu sûr. Elle donne accès à toutes les boutiques de votre compte, pas besoin d'en créer une par boutique.

2. Authentification et boutique visée

Toutes les requêtes utilisent un header Bearer avec votre clé API :

Authorization: Bearer kaoqa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Comme une clé couvre plusieurs boutiques, chaque requête (sauf GET /shops ci-dessous) doit préciser la boutique concernée via l'en-tête X-Shop-Id :

X-Shop-Id: 64f1a2b3c4d5e6f7a8b9c0d1

Vous pouvez aussi passer ?shopId=... en paramètre de requête, ou shopId dans le corps JSON pour les requêtes POST/PUT — l'en-tête reste la méthode recommandée. Récupérez vos ID de boutique facilement (bouton copier) depuis Développeur → Mes boutiques, ou via l'endpoint ci-dessous.

3. Lister mes boutiques

Ne nécessite pas d'en-tête X-Shop-Id — c'est justement là qu'on récupère les ID à utiliser ensuite.

GET https://api.perfaith.tech/api/v1/external/shops
Authorization: Bearer <votre_clé>

→ 200 OK
{
  "success": true,
  "data": {
    "shops": [
      { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Boutique Cocody", "businessType": "retail",
        "city": "Abidjan", "country": "CI", "isActive": true, "currency": "FCFA" }
    ],
    "total": 1
  }
}

4. Récupérer le catalogue produits (d'une boutique)

GET https://api.perfaith.tech/api/v1/external/products?page=1&limit=50
Authorization: Bearer <votre_clé>
X-Shop-Id: <id_boutique>

→ 200 OK
{
  "success": true,
  "data": {
    "products": [
      { "id": "...", "sku": "REF001", "name": "Chemise blanche",
        "price": 15000, "currency": "XOF", "quantity": 12, "unit": "pièce" }
    ],
    "meta": { "total": 128, "page": 1, "limit": 50, "pages": 3 }
  }
}

Un seul produit : GET /api/v1/external/products/:id

5. Créer / mettre à jour un produit

POST https://api.perfaith.tech/api/v1/external/products
Authorization: Bearer <votre_clé>
X-Shop-Id: <id_boutique>
Content-Type: application/json

{
  "name": "Chemise blanche",
  "price": 15000,
  "quantity": 20,
  "sku": "REF001",
  "category": "Chemises"
}

PUT /api/v1/external/products/:id pour une mise à jour (prix, stock...).

6. Créer une commande

Une fois le paiement confirmé côté site externe (ou via l'étape 7 ci-dessous), enregistrez la vente dans Kora OS :

POST https://api.perfaith.tech/api/v1/external/orders
Authorization: Bearer <votre_clé>
X-Shop-Id: <id_boutique>
Content-Type: application/json

{
  "items": [{ "productId": "...", "quantity": 2 }],
  "paymentMethod": "card",
  "externalRef": "WOO-00187",
  "customerName": "Awa Koné",
  "customerPhone": "+18037555352"
}

7. Encaisser un paiement mobile money (DigitalPaye)

Nécessite que la boutique visée ait configuré ses clés DigitalPaye (Paramètres de la boutique → Intégrations) et que votre clé API ait la permission payments:collect.

POST https://api.perfaith.tech/api/v1/external/payments/collect
Authorization: Bearer <votre_clé>
X-Shop-Id: <id_boutique>
Content-Type: application/json

{
  "amount": 15000,
  "operatorCode": "ORANGE_MONEY_CI",
  "externalRef": "WOO-00187",
  "payerPhone": "0700000000",
  "payerFirstName": "Awa"
}

Opérateurs disponibles : ORANGE_MONEY_CI, WAVE_CI, MTN_MONEY_CI, FLOOZ_MONEY_CI. Pour Wave, la réponse contient une wave_launch_url vers laquelle rediriger le client.

Vérifier le statut : GET /api/v1/external/payments/:reference/status

8. Autres ressources disponibles

Toutes les ressources suivent le même schéma REST (GET liste, GET /:id détail, POST création, PUT /:id modification, DELETE /:id suppression), avec la permission correspondante sur votre clé API, et nécessitent toutes l'en-tête X-Shop-Id :

/api/v1/external/categories           (categories:read / categories:write)
/api/v1/external/services              (services:read / services:write)
/api/v1/external/service-categories    (services:read / services:write)
/api/v1/external/stock/adjust          (stock:write)         — POST uniquement
/api/v1/external/suppliers             (suppliers:read / suppliers:write)
/api/v1/external/expenses              (expenses:read / expenses:write)
/api/v1/external/customers             (customers:read / customers:write)
/api/v1/external/credits               (credits:read / credits:write)

Exemple — ajuster un stock :

POST https://api.perfaith.tech/api/v1/external/stock/adjust
Authorization: Bearer <votre_clé>
X-Shop-Id: <id_boutique>

{ "productId": "...", "quantity": 5, "mode": "increment", "reason": "Réassort" }

mode : set (valeur exacte), increment ou decrement.

9. Recevoir des notifications (webhook Kora OS)

Configurez une URL de webhook depuis Développeur → Webhook Kora OS pour recevoir un événement HTTP dès qu'une vente est créée sur n'importe laquelle de vos boutiques, sans avoir à interroger l'API en boucle. Chaque envoi précise shop_id pour identifier la boutique concernée, et est signé :

POST https://votre-site.com/webhooks/kaoqa
X-Kora OS-Signature: sha256=<hmac_hex>
Content-Type: application/json

{
  "event": "sale.created",
  "shop_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "timestamp": "2026-07-13T10:00:00.000Z",
  "data": { "id": "...", "saleNumber": "V20260713-0001", "total": 15000 }
}

Vérifiez la signature en recalculant un HMAC-SHA256 du corps brut avec votre secret webhook, et en la comparant à l'en-tête X-Kora OS-Signature.

Limites

  • 120 requêtes/minute par clé API.
  • Une clé donne accès à toutes les boutiques de votre compte — jamais à celles d'un autre compte.
  • Vous pouvez révoquer une clé à tout moment depuis Développeur.

Plugins WooCommerce / PrestaShop clé-en-main : en préparation. En attendant, cette API REST peut être utilisée directement par un développeur pour connecter n'importe quel site.

WhatsApp