Développeurs

API et webhooks

Branchez votre ERP, votre entrepôt ou vos outils d'automatisation sur votre boutique : lisez les commandes, mettez à jour le stock, recevez les événements en temps réel.

Créer une clé API https://yaliko.com/api/v1

Authentification

Créez une clé dans Réglages → Développeurs (réservé au propriétaire). Envoyez-la dans l'en-tête Authorization: Bearer. Une clé « Lecture » lit ; une clé « Lecture et écriture » peut aussi modifier les commandes et les produits. Gardez-la côté serveur.

Authorization: Bearer yaliko_live_…

Limites

120 requêtes par minute et par clé. Au-delà, l'API répond 429 : attendez un peu et réessayez.

Pagination

Les listes renvoient { data, next_cursor }, les plus récents d'abord. Passez limit (1 à 100, 50 par défaut) et cursor=next_cursor pour la page suivante. next_cursor vaut null à la dernière page.

Erreurs

Une erreur renvoie { error: { code, message } } avec le statut HTTP : 400 corps invalide, 401 clé absente ou révoquée, 403 clé en lecture seule, 404 introuvable dans votre boutique, 422 champ invalide, 429 trop de requêtes.

Les montants sont des entiers dans la devise de la boutique (currency). Les dates sont en ISO 8601, UTC.

Points d'accès

GET `/store`	La boutique de la clé : nom, devise, langue. Pratique pour tester une clé.	lecture
GET `/orders`	Les commandes, les plus récentes d'abord. Filtres : status, created_after, created_before.	lecture
GET `/orders/{id}`	Une commande avec ses articles, le client et la livraison.	lecture
PATCH `/orders/{id}`	Changer status (PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELED), carrier, tracking_number, tracking_url. Mêmes effets que dans l'admin : remise en stock, message au client, points de fidélité.	écriture
GET `/products`	Les produits avec leurs variantes. Filtre : q (dans le nom).	lecture
GET `/products/{id}`	Un produit.	lecture
PATCH `/products/{id}`	Mettre à jour price, compare_at_price, stock et variants: [{ id, price, stock }]. Les clients en attente sont prévenus du retour en stock.	écriture
GET `/customers`	Les clients. Filtres : email, phone.	lecture
GET `/customers/{id}`	Un client.	lecture

Exemple : lister les commandes à préparer

curl https://yaliko.com/api/v1/orders?status=PENDING&limit=2 \
  -H "Authorization: Bearer yaliko_live_…"

{
  "data": [
    {
      "id": "cmuo2k1x40001…",
      "reference": "40001ABC",
      "status": "PENDING",
      "payment": { "mode": "COD", "status": "PENDING", "refunded": 0 },
      "total": 730,
      "currency": "MAD",
      "customer": { "id": "cmung…", "name": "Sara Alaoui", "phone": "212612345678", "email": null },
      "shipping": { "address": "12 rue …", "city": "Casablanca", "carrier": null, "tracking_number": null },
      "items": [{ "product_id": "cmunc…", "name": "Théière", "quantity": 1, "unit_price": 590 }],
      "created_at": "2026-09-30T10:12:00.000Z"
    }
  ],
  "next_cursor": "cmuo2k1x40001…"
}

Exemple : marquer une commande expédiée

curl -X PATCH https://yaliko.com/api/v1/orders/cmuo2k1x40001… \
  -H "Authorization: Bearer yaliko_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "SHIPPED", "carrier": "Amana", "tracking_number": "RR123456789MA" }'

Webhooks

Ajoutez une URL https dans Réglages → Développeurs et choisissez les événements. Nous envoyons un POST JSON signé à chaque événement. Répondez 2xx en moins de 10 secondes ; faites le travail lourd ensuite.

Événements

order.createdUne commande est passée (boutique, paiement par carte confirmé, ou créée dans l'admin).
order.updatedLe statut d'une commande change.
customer.createdUn client crée son compte.

POST /webhooks/yaliko
Yaliko-Event: order.updated
Yaliko-Delivery: cmup…
Yaliko-Signature: t=1790745600,v1=5f2b…

{
  "id": "evt_…",
  "type": "order.updated",
  "created_at": "2026-09-30T10:20:00.000Z",
  "data": { "id": "cmuo2k1x40001…", "status": "SHIPPED", … }
}

Vérifier la signature

L'en-tête Yaliko-Signature contient t (horodatage) et v1 (HMAC-SHA256 de « t.corps » avec le secret du webhook). Calculez-le sur le corps brut, refusez les horodatages de plus de 5 minutes.

import crypto from "node:crypto";

// Express: app.post("/webhooks/yaliko", express.raw({ type: "application/json" }), handler)
function isFromYaliko(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

Nouvelles tentatives

Si votre URL ne répond pas 2xx, nous réessayons après 1 min, 5 min, 30 min, 2 h puis 12 h. L'historique des envois et un bouton « Renvoyer » sont dans les réglages. Un même événement peut arriver deux fois : dédupliquez avec l'id de l'événement.