API REST & webhooks
Mozaiq expose une API JSON sous /api/v1. La lecture publique (pages, articles, produits publiés, catégories, menus) ne demande aucune authentification : idéal pour un site « headless ». L’écriture et les données privées (commandes, clients) exigent une clé d’API.
Clés d’API
Réglages › API & webhooks › Créer une clé : choisissez « Lecture » ou « Lecture et écriture ». La clé (mq_…) n’est affichée qu’une fois. Elle agit avec les permissions de l’utilisateur qui l’a créée (voir Utilisateurs › Rôles et permissions).
curl https://monsite.fr/api/v1/orders -H "Authorization: Bearer mq_xxxxxxxx"Réponses d’erreur : {"error": {"code": 401, "message": "…"}} — 401 (clé absente), 403 (permission), 404, 422 (validation).
Points d’accès
| Méthode | Chemin | Permission | Description |
|---|---|---|---|
| GET | /api/v1 | — | Informations sur le site |
| GET | /api/v1/pages, /api/v1/posts | — | Contenus publiés (page, per_page, search, category) |
| GET | /api/v1/pages/{slug} | — | Contenu complet (blocs + HTML) |
| GET | /api/v1/posts/{id} | edit_content | Contenu par identifiant, avec statut et champs |
| POST | /api/v1/posts | edit_content | Créer : title, html ou blocks, status, excerpt, slug, categories, tags, seo, fields |
| PATCH | /api/v1/posts/{id} | edit_content | Modifier (mêmes champs) |
| DELETE | /api/v1/posts/{id} | edit_content | Corbeille (?force=1 : suppression définitive) |
| GET | /api/v1/products, /api/v1/products/{slug} | — | Catalogue publié |
| POST / PATCH | /api/v1/products[/{id}] | manage_shop | name, price, sale_price, stock, sku, description, short_description, status, categories, images (URL), weight, tax_class |
| DELETE | /api/v1/products/{id} | manage_shop | Dépublie le produit |
| GET | /api/v1/orders | manage_orders | Filtres status, since (date), pagination |
| GET | /api/v1/orders/{id} | manage_orders | Détail avec lignes |
| PATCH | /api/v1/orders/{id} | manage_orders | status, note, tracking_number, carrier |
| GET | /api/v1/customers | manage_orders | Clients (50 par page) |
Les mêmes routes existent pour les types de contenu personnalisés : /api/v1/{type}. La publication est refusée (passage en brouillon) si l’utilisateur n’a pas publish_content. Le HTML reçu est assaini.
Webhooks
Réglages › API & webhooks › Nouveau webhook : URL, événements (ou « Tous »). Chaque appel est un POST JSON :
{ "event": "order.created", "id": "3f2a…", "created_at": "2026-09-25T14:08:34+02:00", "site": "https://monsite.fr", "data": { … } }En-têtes : X-Mozaiq-Event, X-Mozaiq-Delivery, et X-Mozaiq-Signature: sha256=<HMAC-SHA256 du corps avec le secret du webhook>.
$ok = hash_equals('sha256=' . hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_MOZAIQ_SIGNATURE'] ?? '');Événements : order.created, order.status_changed, order.refunded, product.saved, product.deleted, stock.low, content.published, content.deleted, customer.created, comment.created, review.created, form.submitted.
Envoi par la tâche planifiée « Envoi des webhooks » (chaque minute) ; en cas d’échec (réponse hors 2xx) : nouvelles tentatives après 1 min, 5 min, 30 min, 2 h et 12 h. Un webhook est désactivé après 20 échecs consécutifs. Le journal des envois (avec « Renvoyer ») est dans la même page.