API développeur Mystoq

Démarrage rapide

Trois étapes, de zéro à votre première commande par API :

1. Créez une clé API depuis Tableau de bord → Développeurs (portée read ou write).
2. Envoyez la clé dans l’en-tête Authorization: Bearer à chaque requête.
3. Appelez GET /v1/products, puis enregistrez une URL Webhook pour recevoir les événements.

Introduction

L’API Mystoq est RESTful, renvoie du JSON et est sécurisée par clés API. Chaque requête s’exécute uniquement dans votre boutique (isolation totale). Créez votre clé depuis Tableau de bord → Développeurs.

Authentification

Transmettez votre clé dans l’en-tête Authorization en Bearer. Les clés ont la forme msq_<prefix>_<secret> ; la partie secrète n’est affichée qu’une seule fois, à la création.

# Chaque requête nécessite cet en-tête
Authorization: Bearer msq_ab12cd34_your_secret_here

URL de base & limites

Produits

Liste les produits publiés de votre boutique (status = active), paginés.

Paramètres (optionnels)

# Example
curl "https://mystoq.com/api/v1/products?per_page=2&search=jacket" \
  -H "Authorization: Bearer msq_ab12cd34_secret" \
  -H "Accept: application/json"

// Response
{
  "data": [
    { "id": 1027, "name": "Women's jacket", "slug": "womens-jacket",
      "price": 2000, "compare_price": 2800, "sku": "JCK-01",
      "stock": 100, "status": "active", "category_id": 4,
      "images": ["https://…/p1.jpg"] }
  ],
  "meta": { "current_page": 1, "per_page": 2, "total": 57, "last_page": 29 }
}

Un seul produit. Renvoie 404 s’il est introuvable ou non publié.

Commandes

Liste les commandes de votre boutique (paginées, les plus récentes d’abord).

Paramètres (optionnels)

Une commande avec ses articles et les informations du client.

// Réponse de la commande
{
  "data": {
    "id": 5821, "reference": "ORD-5821", "status": "pending",
    "payment_method": "cod", "payment_status": "unpaid",
    "subtotal": 2000, "shipping_cost": 500, "discount": 0, "total": 2500,
    "delivery_type": "home", "wilaya_id": 16, "commune": "Bab Ezzouar",
    "customer": { "name": "Ahmed Ben Ali", "phone": "0555123456" },
    "items": [ { "product_id": 1027, "name": "Women's jacket", "price": 2000, "qty": 1, "total": 2000 } ],
    "created_at": "2026-07-18T20:00:00Z"
  }
}

Créer une commande

Créez une commande par programme. Nécessite une clé avec la portée write. La commande applique toutes les règles : recalcul du prix côté serveur, réservation du stock et frais de livraison par wilaya.

Corps de la requête

curl -X POST "https://mystoq.com/api/v1/orders" \
  -H "Authorization: Bearer msq_ab12cd34_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Ahmed Ben Ali", "phone": "0555123456", "wilaya_id": 16, "commune": "Bab Ezzouar" },
    "items": [ { "product_id": 1027, "qty": 1 } ],
    "payment_method": "cod",
    "delivery_type": "home"
  }'

Webhooks

Enregistrez une URL https dans le tableau de bord pour recevoir des notifications POST instantanées lors des événements.

// Charge utile envoyée à votre URL
{
  "event": "order.created",
  "created_at": "2026-07-11T20:00:00Z",
  "data": {
    "id": 5821, "reference": "ORD-5821", "status": "pending",
    "total": 2500, "customer": { "name": "Ahmed", "phone": "0555…" }
  }
}

Vérifier la signature

Chaque Webhook porte un en-tête X-Mystoq-Signature = sha256=HMAC(secret, rawBody). Vérifiez-le pour confirmer l’origine et l’intégrité.

// Node.js — exemple de vérification
const crypto = require("crypto");
const expected = "sha256=" +
  crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (expected === req.headers["x-mystoq-signature"]) { /* de confiance */ }

Erreurs