Développeurs — Intégration e-commerce

Démarrage — 5 minutes

1. Récupère ta clé API

Ta clé est fournie par MySargal (elle est liée à ta boutique). Demande-la sur WhatsApp ou par mail à [email protected]. Elle ressemble à :

msk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Méthode recommandée : envoie la clé dans l'en-tête HTTP x-api-key (jamais dans l'URL), en HTTPS, depuis ton serveur uniquement :

POST https://iiocxlvcuoqafzlisqwd.supabase.co/functions/v1/api-order
x-api-key: TA_CLE
Content-Type: application/json

Pour les plateformes dont les webhooks ne permettent pas d'ajouter un en-tête (Shopify, webhooks natifs WooCommerce), une URL webhook avec la clé en paramètre reste acceptée en compatibilité. Une clé dans une URL peut apparaître dans des journaux : ne l'utilise que là où l'en-tête est impossible, et régénère-la si elle a pu fuiter.

https://iiocxlvcuoqafzlisqwd.supabase.co/functions/v1/api-order?key=TA_CLE

Shopify

Admin Shopify → Paramètres → Notifications → onglet Webhooks
Créer un webhook : Événement = Paiement de commande (Order payment), Format = JSON
URL = ton URL webhook ci-dessus → Enregistrer

C'est tout. À chaque commande payée : si le client a un numéro de téléphone, sa carte est trouvée (ou créée + envoyée par WhatsApp) et ses points sont crédités selon ta règle « 1 point = X FCFA ».

WooCommerce (WordPress)

Recommandé : installe le plugin MySargal pour WooCommerce (clé envoyée dans l'en-tête x-api-key, points crédités au paiement, retirés en cas de remboursement, cartes cadeaux et récompenses au checkout). À défaut, webhook natif :

Admin WordPress → WooCommerce → Réglages → Avancé → Webhooks
Ajouter un webhook : Sujet = Commande mise à jour (ou « Commande créée »), Statut = Actif
URL de livraison = ton URL webhook → Enregistrer

Les commandes en statut pending / cancelled / refunded / failed sont ignorées automatiquement — pas de points sur les commandes annulées.

Secret webhook (signature des commandes)

Quand la clé API voyage dans l'URL du webhook, elle peut fuiter (journaux, captures d'écran). Pour qu'une URL volée ne permette pas de créditer des points, MySargal vérifie la signature HMAC-SHA256 que Shopify et WooCommerce ajoutent à chaque envoi (en-têtes X-Shopify-Hmac-Sha256 et X-WC-Webhook-Signature, base64 du HMAC du corps brut). Dès qu'une signature est présente, elle est contrôlée ; une signature fausse est refusée (401).

Où trouver / renseigner le secret

Shopify : Admin → Paramètres → Notifications → Webhooks. En bas de la liste, Shopify affiche « Tous vos webhooks seront signés avec … ». Copie cette valeur et transmets-la à MySargal (WhatsApp ou [email protected]) : l'équipe la rattache à ta clé API.
WooCommerce (webhook natif) : MySargal te fournit un secret (format whs_…). Colle-le dans le champ Secret du webhook (WooCommerce → Réglages → Avancé → Webhooks). WooCommerce signera alors chaque envoi avec ce secret.
Plugin MySargal pour WooCommerce, Odoo, site custom : rien à faire. Ces intégrations envoient la clé dans l'en-tête x-api-key depuis le serveur et ne signent pas ; elles ne doivent pas être passées en mode « signature exigée ».

Mode « signature exigée »

Une fois ta plateforme configurée, demande à MySargal d'activer la signature exigée sur ta clé : tout appel sans signature valide sera alors refusé, même avec la bonne clé. Tant que ce mode n'est pas activé, la clé API suffit (compatibilité), et les signatures reçues sont tout de même vérifiées.

Si le secret a pu fuiter : régénère ta clé API depuis le panel (Réglages → Clé API) — un nouveau secret est créé en même temps — puis recolle la nouvelle URL et le nouveau secret dans ta plateforme.

Odoo

Odoo se connecte via l'API MySargal, sans module à installer (Odoo auto-hébergé). Activez le mode développeur, puis Paramètres → Technique → Actions automatisées : sur le modèle Commande (sale.order) ou Point de vente, déclencheur au paiement (facture payée / commande POS payée, pas à la simple confirmation du devis), avec ce code :

for order in records:
    partner = order.partner_id
    phone = partner.phone or partner.mobile
    if not phone:
        continue
    requests.post(
        "https://iiocxlvcuoqafzlisqwd.supabase.co/functions/v1/api-order",
        headers={"x-api-key": "TA_CLE", "Content-Type": "application/json"},
        json={
            "phone": phone,
            "name": partner.name,
            "amount": int(order.amount_total),
            "order_id": order.name,
            "idempotency_key": "odoo-" + order.name,
        },
        timeout=10,
    )

À chaque commande payée, les points du client sont crédités automatiquement. Pour Odoo Online (SaaS), où les appels réseau sont restreints, un petit module MySargal dédié peut être fourni sur demande.

Site custom (n'importe quel langage)

Appelle l'endpoint après chaque paiement confirmé :

curl -X POST \
  "https://iiocxlvcuoqafzlisqwd.supabase.co/functions/v1/api-order" \
  -H "x-api-key: TA_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+221771234567",
    "name": "Awa Ndiaye",
    "amount": 15000,
    "order_id": "CMD-2024-001"
  }'

Réponse :

{
  "success": true,
  "card_code": "LC-A1B2C3",
  "card_url": "https://mysargal.com/c/?code=LC-A1B2C3",
  "new_client": true,
  "points_added": 15,
  "total_points": 15
}

Champs

phone (requis) — numéro du client, avec indicatif
amount — montant FCFA (points calculés selon la règle de ta boutique). Sans montant : 1 commande = 1 point
points — pour forcer un nombre de points précis (ignore le calcul)
order_id — fortement conseillé : empêche tout double crédit si le webhook est rejoué
idempotency_key — optionnel (8 à 100 caractères) : un rejeu avec la même clé renvoie la même réponse sans recréditer

Les autres endpoints

Même authentification : en-tête x-api-key (recommandé ; ?key= reste accepté en compatibilité) :

Consulter un solde

POST /functions/v1/api-balance   { "card_code": "LC-A1B2C3" }

Créditer des points (scan caisse / POS)

POST /functions/v1/api-scan      { "card_code": "LC-A1B2C3", "points": 5 }

Utiliser une récompense (déduction en caisse)

POST /functions/v1/api-redeem    { "card_code": "LC-A1B2C3" }
→ { "success": true, "reward": "Café offert", "points_used": 50, "points_remaining": 10 }
→ 402 si pas assez de points (avec points_disponibles / points_requis)

Remboursement / annulation d'une commande

POST /functions/v1/api-reverse   { "order_id": "CMD-2024-001", "kind": "refund" }
→ { "success": true, "points_removed": 15, "points_recredited": 0 }

Retire les points gagnés sur la commande (sans jamais rendre le solde négatif) et rend les points dépensés en récompense pour cette commande. Idempotent : un second appel pour la même commande ne fait rien de plus. kind : refund ou cancel.

Flux POS complet : api-balance renvoie reward_ready: true et la liste rewards_available dès que le client a atteint sa récompense → l'écran de caisse l'affiche → api-redeem déduit les points au moment de l'achat. La carte Wallet du client se met à jour aussitôt.

Bon à savoir

Tout passe en HTTPS ; les clés sont révocables à tout moment
Les jours « points x2 » de la boutique s'appliquent aussi aux commandes en ligne
Un nouveau client reçoit sa carte par WhatsApp automatiquement
La carte Apple/Google Wallet du client se met à jour en quelques secondes

Besoin d'aide pour l'intégration ?

On la fait avec toi, gratuitement.

Parler à l'équipe sur WhatsApp

Connecte ta boutique en ligne à MySargal