API boutique v2
Gérez votre boutique en ligne depuis votre serveur ou depuis un assistant : création et réglages, catégories, articles et photos, livraison, pages, publication, commandes, messages de la page Contact, assistance IA. Même norme que l'API v2 (une clé par appel, enveloppes data / error, messages en français), mêmes règles que la page Ma boutique du portail : limites fixées par CashChap, identité vérifiée, contrôle des fichiers, journal d'activité.
Authentification
Authorization: Bearer SKLIVE_VOTRE_CLE_SECRETE
Content-Type: application/json
- Clé secrète LIVE du service (
SKLIVE_…, Portail › Développeurs › Clés API & MCP), côté serveur uniquement. La boutique vend toujours en mode Live : une cléSKSANDBOX_…répond 403live_key_required, une clé publique, de terminal ou de session 403secret_key_required. - Clé absente : 401
missing_api_key(en-têteWWW-Authenticate) ; clé inconnue, mal formée ou désactivée : 401invalid_api_key. La clé est comparée en temps constant, jamais journalisée. - La boutique est celle du service de la clé (une par service). Un service sans boutique répond 404
storefront_not_foundavecdetails.can_create; créez-la avecPOST /v2/boutique. - Toute écriture est inscrite dans Compte › Journal d'activité du portail (action « BOUTIQUE EN LIGNE (API) », mode Live, adresse IP et User-Agent de l'appel).
- Clé MCP du compte (
MKLIVE_…, Portail › Développeurs › Clés API & MCP › Clé MCP du compte, titulaire seul) : une seule clé pour tout le compte, faite pour le serveur MCP hébergé. Acceptée par cette API à la place de la clé secrète du service, avec l'en-têteX-CashChap-Service: <identifiant du service>(obligatoire : 403service_not_foundsinon, ou si le service n'est pas du compte) ; clé inconnue ou révoquée : 401invalid_mcp_key. Le contexte est l'environnement Live du service désigné ; tout le reste est identique. Les identifiants des services se lisent surPOST /v2/compte/mcp/session(même en-têteAuthorization), qui rend le compte, ses services, leurs clés secrètes Live et Sandbox et l'état de leur boutique ; réponse jamais mise en cache.
Réponses, pagination, idempotence, débit
HTTP/1.1 200 OK
CashChap-Version: 2.6.0
CashChap-Boutique-Version: 1.0.0
X-Request-Id: req_01JBXK8W2M3Q4Z5V6T7Y8H9N0P
{
"data": { "id": "…", "object": "storefront", "mode": "live", "slug": "ma-boutique", "status": "draft", "...": "..." },
"meta": { "request_id": "req_01JBXK8W2M3Q4Z5V6T7Y8H9N0P" }
}
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "validation_failed",
"type": "validation_error",
"message": "La requête contient 1 champ invalide.",
"details": { "fields": [ { "field": "slug", "code": "slug_unavailable", "message": "Cette adresse est réservée par CashChap. Choisissez-en une autre." } ] },
"request_id": "req_…",
"doc_url": "https://cashchap.com/docs/api-boutique#erreurs"
}
}
- Enveloppes identiques à l'API v2 :
{"data", "meta"}ou{"error"}, jamais de champsuccess;X-Request-Idreprendmeta.request_id. Les champs sont en anglaissnake_case, les dates en ISO 8601 UTC, les montants dans la devise du service (currency, XOF sans décimales). Un champ inconnu est refusé (validation_failed, codeunknown_field) ; un corps qui n'est pas un objet JSON répond 400invalid_json. - Versions :
CashChap-Versiondonne la version de la norme v2 publiée (2.8.0),CashChap-Boutique-Versioncelle de cette API (1.0.0) ; les ajouts compatibles changent la version mineure. - Pagination des articles, commandes et messages par curseur :
limit(1 à 200, 50 par défaut),cursor=meta.next_cursorde la page précédente ;meta.has_more,meta.total. - Idempotence des créations (
POST /v2/boutique, catégories, articles, photos, analyses, génération, réponse à un message) : en-têteIdempotency-Keyfacultatif (1 à 128 caractères : lettres, chiffres,-,_). Même clé et même corps : même réponse, en-têteIdempotent-Replayed: true; même clé et corps différent : 409idempotency_conflict; requête encore en cours : 409request_in_progress. Mémoire : 24 h. - Débit, par clé et par minute : 300 lectures, 60 écritures, 10 lancements IA. Au-delà : 429
rate_limitedavecRetry-After. - Actions irréversibles (zone Danger, suppression groupée, suppression des brouillons IA) : le corps doit porter
"confirm": true, sinon 422confirmation_required.
La boutique
| Route | Rôle |
|---|---|
GET /v2/boutique | Objet storefront : adresse (slug, url), status (draft, published, suspended, offline : mise hors ligne pour inactivité, voir Boutique inactive), suspended_by (boutique suspendue : team par l'équipe CashChap, merchant par vous ; sinon null) et suspension_message (message de l'équipe, tel quel, ou null ; voir Boutique suspendue par CashChap), nom, présentation, thème et couleur, logo et bannière, téléphone, WhatsApp et adresse (montrés au client après son paiement seulement), options de livraison, seo, pixels, kyc et daily_limit, compteurs (counts), limites de la plateforme (limits), disponibilité de l'IA. |
POST /v2/boutique | Création en brouillon : public_name (2 à 80), slug (3 à 30 caractères, minuscules, chiffres, tirets ; noms de la plateforme réservés) et, facultatifs, description, theme, accent_color (#rrggbb), phone, whatsapp, address, seo {title, description, keywords, auto}, pixels {meta, tiktok}, logo et banner (image). Identité du promoteur vérifiée exigée (403 account_not_activated) ; entreprise pas encore validée (Marchand Essentiel) : daily_limit 200 000 XOF (plafond d'encaissement du jour du compte, réglé par CashChap). 201. |
PATCH /v2/boutique | Réglages : seuls les champs envoyés changent (mêmes champs que la création, sauf slug, plus pickup_enabled et delivery_enabled). logo: null retire le logo. Un texte SEO saisi passe en source manual : l'IA ne l'écrase plus. |
GET /v2/boutique/themes | Les treize designs (id, label, accent_color…), les univers de démonstration et les limites. |
POST /v2/boutique/slug | Changer l'adresse (slug) : une fois par 30 jours (409 slug_change_too_soon), l'ancienne redirige pendant 30 jours. |
POST /v2/boutique/publier · /suspendre | Mise en ligne (au moins un article actif, sinon 409 storefront_not_publishable) ; suspension (page « momentanément indisponible »). Boutique suspendue par l'équipe CashChap (suspended_by: team) : les deux répondent 403 storefront_suspended_by_team ; contactez le support. PATCH /v2/boutique reste permis. |
DELETE /v2/boutique/logo · /banner | Retrait du logo (icônes régénérées) ou de la bannière. |
POST /v2/boutique/demo · DELETE | Articles de démonstration d'un univers (universe : mode, alimentation, electronique, beaute, services, artisanat), marqués demo ; suppression de tous les articles de démonstration. |
POST /v2/boutique/danger | action : delete_all_articles, delete_all_categories ou reset (brouillon, textes et thème par défaut, adresse conservée, e-mail au titulaire), avec confirm: true. Les commandes sont toujours conservées. Fermée pendant une suspension par l'équipe CashChap (403 storefront_suspended_by_team). |
curl -X POST https://cashchap.com/v2/boutique \
-H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: creation-boutique-1" \
-d '{
"public_name": "Boutique Afi",
"slug": "boutique-afi",
"description": "Pagnes, robes et accessoires cousus à Cotonou.",
"theme": "wax",
"accent_color": "#d97706",
"seo": { "auto": true }
}'
Images : logo, bannière, photos
Une image se donne sous trois formes, dans un objet : {"base64": "…", "filename": "photo.jpg"} (ou une URL de données data:image/jpeg;base64,…), {"url": "https://cashchap.com/vitrine-image/signee/…"} (lien signé CashChap : l'image est copiée, rien n'est téléchargé) ou, pour les photos d'article seulement, {"url": "https://…"} : le serveur télécharge l'image (hôte public résolu, https, sans redirection, 4 Mo au plus). Toute image passe les contrôles de Ma boutique : nom et contenu suspects refusés (malicious_file_rejected, inscrit dans le journal du compte), type réel vérifié, réencodage et redimensionnement par le serveur, miniature. Formats : JPEG, PNG, GIF, WebP, AVIF, HEIC, BMP, TIFF, SVG assaini.
Catégories
| Route | Rôle |
|---|---|
GET /v2/boutique/categories | Liste ordonnée (position), avec articles_count ; meta.uncategorized_articles. |
POST /v2/boutique/categories | name (80 car.), description (200), active. 30 catégories au plus ; un nom déjà pris (ou trop proche) répond 409 category_name_taken. 201. |
PATCH /v2/boutique/categories/{id} | name, description, active, position. |
POST /v2/boutique/categories/ordre | ids dans l'ordre voulu (les catégories absentes suivent). |
DELETE /v2/boutique/categories/{id} | Suppression ; ses articles deviennent « sans catégorie ». |
Articles, variantes, photos
| Route | Rôle |
|---|---|
GET /v2/boutique/articles | Liste paginée ; filtres category_id (ou none), active, featured, demo, ai_draft, search. |
GET /v2/boutique/articles/{id} | Fiche : prix, promo, effective_price, strikethrough_price, stock, photos, variants, videos [{id, type : file | link, url, bytes}] (video : la première, compatibilité), media_count (photos et vidéos), seo, url publique. |
POST /v2/boutique/articles | name (2 à 120), price (> 0, arrondi à la devise), description, promo {type: none | price | percent, price, percent (1 à 99), starts_at, ends_at (une date seule est lue à l'heure de Porto-Novo)}, stock (null = illimité), category_id, active, featured (6 au plus), position, variants [{name, price, stock, active}], video_url (YouTube, Vimeo, TikTok), photos [image…]. Les photos refusées sont détaillées dans meta.photos. Médias : photos et vidéos ensemble, media_per_article au plus (limits, 10 par défaut), avec les plafonds photos_per_article et videos_per_article ; au-delà, 422 validation_failed. Limite d'articles de la plateforme : 409 article_limit_reached. 201. |
PATCH /v2/boutique/articles/{id} | Modification partielle (mêmes champs sauf photos) ; video_url remplace les liens vidéo de l'article (null : les retire), les fichiers vidéo restent ; variants remplace la liste (une variante avec id est conservée) ; active, featured, category_id (déplacement), position. |
POST /v2/boutique/articles/ordre | ids dans l'ordre voulu ; list : catalog (défaut) ou featured (« À la une »). |
POST /v2/boutique/articles/groupe | Action groupée : action (move + category_id, feature, unfeature, hide, show, delete + confirm), ids (500 au plus). |
DELETE /v2/boutique/articles/{id} | Suppression (photos, variantes, vidéo) ; les commandes passées gardent le nom de l'article. |
POST /v2/boutique/articles/{id}/photos | photos [image…] : résultat par photo dans meta.results, liste des photos en data. Limites par article : photo_limit_reached (photos), media_limit_reached (photos et vidéos ensemble) ; meta.media_count, meta.media_limit. 201 dès qu'une photo est acceptée. |
POST /v2/boutique/articles/{id}/photos/ordre | ids des photos dans l'ordre voulu. |
POST /v2/boutique/photos/{id}/principale | Photo principale. |
PATCH /v2/boutique/photos/{id} | alt (texte alternatif, 125 car., source manual), main. |
DELETE /v2/boutique/photos/{id} · /articles/{id}/video | ?id= (une vidéo de videos[].id) ou toutes les vidéos. Suppression d'une photo (fichier et miniature retirés) ; retrait de la vidéo. |
POST /v2/boutique/articles/{id}/medias/{media}/deplacer | Déplace une photo (photos[].id) ou une vidéo (videos[].id) vers un autre article de la même boutique : target_article_id (ou article_cible), position facultative (fin par défaut). Le fichier ne bouge pas ; texte alternatif, dimensions et poids suivent ; la photo suivante devient principale de l'article d'origine. Cible pleine : 409 media_limit_reached ou video_limit_reached ; média absent : 404 media_not_found. Rend from et to (fiches des deux articles). |
curl -X POST https://cashchap.com/v2/boutique/articles \
-H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: article-robe-wax-1" \
-d '{
"name": "Robe en pagne wax",
"description": "Robe longue taillée dans un pagne authentique, doublure en coton.",
"price": 18000,
"promo": { "type": "percent", "percent": 20, "ends_at": "2026-12-31" },
"stock": 12,
"category_id": "9b2f1a3c-0000-4000-8000-00000000abcd",
"variants": [ { "name": "Taille M" }, { "name": "Taille L" }, { "name": "Taille XL", "stock": 2 } ],
"photos": [ { "url": "https://photos.exemple.com/robe-wax.jpg" } ]
}'
Livraison et pages
| Route | Rôle |
|---|---|
GET /v2/boutique/livraison | pickup_enabled, delivery_enabled, zones (nom, fee, delay). |
POST /v2/boutique/livraison | Remplacement d'un bloc : pickup_enabled, delivery_enabled, zones [{id (pour garder une zone), name, fee, delay}]. Sans zone, la livraison se ferme et le retrait en boutique est forcé. |
GET /v2/boutique/pages | Les trois pages du menu : about, delivery, contact. |
POST /v2/boutique/pages/{type} | title (80), content (5 000, texte sans HTML), active. La page contact est toujours visible (formulaire relayé par CashChap) : seul son titre se règle, aucune coordonnée du vendeur n'y figure. |
Commandes
| Route | Rôle |
|---|---|
GET /v2/boutique/commandes | Liste paginée, de la plus récente à la plus ancienne ; status : pending, paid, failed, expired, cancelled, to_deliver (payées, non livrées), deposit (acompte reçu) ; from, to, search. meta.totals_by_status. Téléphones masqués. |
GET /v2/boutique/commandes/{id} | Détail synchronisé avec les paiements : status, settlement (full, deposit_pending, deposit_received), delivery_state et next_delivery_state, montants, customer (téléphone en clair), delivery (mode, zone, adresse structurée, position, contact), lines, transaction, payment_url (nul tant qu'un paiement validé est en cours de prise en compte : status_label « Paiement reçu, en cours de prise en compte »), tracking_url. |
POST /v2/boutique/commandes/{id}/livraison | state : prepared, shipped, delivered, dans l'ordre, pour une commande payée (ou acompte reçu) ; le client est prévenu par e-mail. Sinon 409 delivery_state_invalid. |
POST /v2/boutique/commandes/{id}/annuler | Annulation d'une commande encore payable (sans acompte reçu, sans paiement reçu ni paiement attendant la confirmation du client) : liens de paiement désactivés. Sinon 409 order_not_cancellable, avec la raison dans le message. |
Messages de la page Contact
| Route | Rôle |
|---|---|
GET /v2/boutique/messages | Liste paginée ; status : new, read, replied, spam ; search ; meta.unread. La lecture ne change jamais le statut. |
GET /v2/boutique/messages/{id} | Détail : texte complet, téléphone en clair, article et commande concernés, réponses envoyées. |
POST /v2/boutique/messages/{id}/statut | status : read (marquer lu), replied, spam, new. |
POST /v2/boutique/messages/{id}/repondre | text (2 à 3 000 car.) : e-mail envoyé par CashChap au nom de la boutique, message d'origine cité, journalisé. Sans adresse e-mail du client : 422 message_reply_impossible. 201. |
Assistance IA
Disponible quand CashChap l'active (GET /v2/boutique/ia : available, quota_remaining). Sinon les lancements répondent 503 ai_unavailable ; quota du jour épuisé : 429 ai_quota_exceeded. Les traitements longs sont asynchrones : la route de lancement répond 202 avec l'objet et son status (pending, processing, completed, failed, confirmed) ; interrogez la route d'état jusqu'à completed, puis confirmez les brouillons.
| Route | Rôle |
|---|---|
POST /v2/boutique/analyses | Analyse de photos : photos [{base64, filename}] (30 au plus par défaut). Chaque photo passe les contrôles des photos d'article. 202. |
GET /v2/boutique/analyses · /analyses/{id} | Analyses récentes ; état d'une analyse avec ses drafts (index, name, description, category, price, variants, photos, state). |
POST /v2/boutique/analyses/{id}/confirmer | lines [{index, name, price, category, description, variants (« Taille M, Taille L »)}], active : articles créés avec leurs photos. 201. |
DELETE /v2/boutique/analyses/{id} | Suppression d'une analyse et de ses fichiers. |
POST /v2/boutique/generation | Génération d'articles : category_ids (catégories existantes, 10 au plus), count (1 à 10 par catégorie), theme. Les brouillons sont de vrais articles, inactifs, marqués ai_draft, avec une image provisoire. 202. |
GET /v2/boutique/generation · /generation/{id} | Générations récentes ; état d'une génération avec draft_articles. |
POST /v2/boutique/generation/confirmer | lines [{id, name, price, description, category_id, variants}] : mis en vente (référencement IA planifié). |
DELETE /v2/boutique/generation/brouillons | Efface les brouillons IA non confirmés (confirm: true). |
POST /v2/boutique/referencement | Régénère tout le référencement (accueil et articles) en tâche de fond ; les textes saisis à la main sont conservés. 202. |
POST /v2/boutique/referencement/boutique · /referencement/articles/{id} | Référencement immédiat de la page d'accueil ou d'un article (titre, description, mots-clés, textes alternatifs des photos). |
# 1. Lancer l'analyse (202)
curl -X POST https://cashchap.com/v2/boutique/analyses \
-H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" -H "Content-Type: application/json" \
-d "{\"photos\": [{\"base64\": \"$(base64 -w0 robe.jpg)\", \"filename\": \"robe.jpg\"}]}"
# 2. Interroger l'état jusqu'à "status": "completed"
curl https://cashchap.com/v2/boutique/analyses/ANALYSE_ID -H "Authorization: Bearer $CASHCHAP_CLE_SECRETE"
# 3. Confirmer les brouillons corrigés (201)
curl -X POST https://cashchap.com/v2/boutique/analyses/ANALYSE_ID/confirmer \
-H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" -H "Content-Type: application/json" \
-d '{"lines": [{"index": 0, "name": "Robe en pagne wax", "price": 18000, "category": "Mode", "variants": "Taille M, Taille L"}], "active": true}'
Serveur MCP
Le serveur MCP officiel @cashchap/mcp expose chaque route de cette API sous la forme d'un outil boutique_* pour les assistants (Claude Desktop, Claude Code, Cursor…) : boutique_voir, boutique_creer, boutique_modifier, boutique_publier, boutique_categories_*, boutique_articles_*, boutique_photos_*, boutique_livraison_*, boutique_pages_*, boutique_commandes_*, boutique_messages_*, boutique_analyse_*, boutique_generation_*, boutique_referencement_*. Il appelle CASHCHAP_PORTAIL_URL (https://cashchap.com par défaut) et exige une confirmation explicite pour les actions destructrices. Variable CASHCHAP_MCP_BOUTIQUE : true (gestion complète, défaut), lecture (consultation seule) ou false.
Serveur hébergé et clé MCP du compte
Le serveur hébergé par CashChap, https://mcp.cashchap.com/mcp, ne demande aucune installation. Dans le portail, Développeurs › Clés API & MCP › Clé MCP du compte, le titulaire crée sa clé MKLIVE_… après un code de vérification (le second facteur de la connexion : code reçu par e-mail ou application d'authentification) ; elle est affichée une seule fois. Un e-mail « Clé MCP du compte créée / régénérée / révoquée » part à chaque événement et l'action est inscrite au journal d'activité (« CLÉ MCP »). Pour la revoir, il faut la régénérer (l'ancienne cesse de fonctionner) ; elle se révoque en un clic.
Brancher votre assistant
Tous les assistants parlent au même serveur, https://mcp.cashchap.com/mcp (transport HTTP « streamable »), avec le même en-tête Authorization: Bearer MKLIVE_… ; seule la façon de le déclarer change. Ces blocs figurent aussi dans le portail (carte « Clé MCP du compte », section Brancher votre assistant), pré-remplis avec la clé au moment où elle est affichée. Ici, remplacez MKLIVE_VOTRE_CLE par votre clé.
Claude Code (Terminal, une commande) : Dans le terminal, une seule commande ; le serveur est disponible dans toutes vos sessions Claude Code.
claude mcp add --transport http cashchap https://mcp.cashchap.com/mcp --header "Authorization: Bearer MKLIVE_VOTRE_CLE"
Claude Desktop (Fichier claude_desktop_config.json) : Réglages › Développeur › Modifier la configuration. Le pont mcp-remote (Node.js) transmet l'en-tête ; les connecteurs personnalisés de Claude.ai n'acceptent pas de clé (OAuth seulement).
{
"mcpServers": {
"cashchap": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.cashchap.com/mcp",
"--header",
"Authorization:${CASHCHAP_AUTH}"
],
"env": {
"CASHCHAP_AUTH": "Bearer MKLIVE_VOTRE_CLE"
}
}
}
}
Cursor (Fichier ~/.cursor/mcp.json (ou .cursor/mcp.json du projet)) : Réglages › MCP › Add new global MCP server ouvre ce fichier ; collez le bloc puis vérifiez le voyant vert.
{
"mcpServers": {
"cashchap": {
"url": "https://mcp.cashchap.com/mcp",
"headers": {
"Authorization": "Bearer MKLIVE_VOTRE_CLE"
}
}
}
}
VS Code (GitHub Copilot) (Fichier .vscode/mcp.json du projet) : Commande « MCP: Add Server » ou ce fichier à la racine du projet ; démarrez le serveur depuis la vue Extensions › MCP Servers.
{
"servers": {
"cashchap": {
"type": "http",
"url": "https://mcp.cashchap.com/mcp",
"headers": {
"Authorization": "Bearer MKLIVE_VOTRE_CLE"
}
}
}
}
Windsurf (Fichier ~/.codeium/windsurf/mcp_config.json) : Réglages › Cascade › MCP › View raw config ouvre ce fichier ; redémarrez Windsurf après l'enregistrement.
{
"mcpServers": {
"cashchap": {
"serverUrl": "https://mcp.cashchap.com/mcp",
"headers": {
"Authorization": "Bearer MKLIVE_VOTRE_CLE"
}
}
}
}
Gemini CLI (Fichier ~/.gemini/settings.json) : Ajoutez le bloc mcpServers au fichier (ou créez-le) ; la commande /mcp dans Gemini CLI liste les outils trouvés.
{
"mcpServers": {
"cashchap": {
"httpUrl": "https://mcp.cashchap.com/mcp",
"headers": {
"Authorization": "Bearer MKLIVE_VOTRE_CLE"
}
}
}
}
Codex (OpenAI) (Fichier ~/.codex/config.toml) : Ajoutez cette table au fichier ; pour ne pas écrire la clé dans le fichier, remplacez http_headers par bearer_token_env_var = "CASHCHAP_MCP_CLE" et exportez la variable.
[mcp_servers.cashchap]
url = "https://mcp.cashchap.com/mcp"
http_headers = { "Authorization" = "Bearer MKLIVE_VOTRE_CLE" }
API OpenAI (Responses) (Outil de type mcp dans la requête) : Pour vos propres programmes. L'application ChatGPT n'accepte pas de clé pour ses connecteurs (OAuth ou sans authentification) : elle n'est pas prise en charge pour l'instant.
{
"tools": [
{
"type": "mcp",
"server_label": "cashchap",
"server_url": "https://mcp.cashchap.com/mcp",
"headers": {
"Authorization": "Bearer MKLIVE_VOTRE_CLE"
},
"require_approval": "never"
}
]
}
Autre client MCP (Paramètres à reporter) : Tout client qui accepte un serveur MCP distant (HTTP) avec un en-tête : Mistral, Cline, Continue, Zed, n8n, Make…
Transport : HTTP (streamable)
Adresse : https://mcp.cashchap.com/mcp
En-tête : Authorization: Bearer MKLIVE_VOTRE_CLE
Avec cette clé, le serveur MCP connaît tout le compte : les outils get_account et list_services présentent le marchand et ses services ; chaque outil accepte un paramètre facultatif service (nom, adresse ou identifiant). Un seul service : il est implicite ; plusieurs : l'assistant demande lequel. Les outils de paiement utilisent la clé secrète du service (Live par défaut, mode: "sandbox" pour le mode test) sur api.cashchap.com ; les outils boutique_* utilisent la clé de compte avec l'en-tête X-CashChap-Service sur cette API. Une clé secrète de service (SKLIVE_…, SKSANDBOX_…) continue de fonctionner comme avant, pour ce seul service.
Codes d'erreur
Codes propres à l'API boutique, en plus des codes communs de la norme v2 (missing_api_key, invalid_api_key, secret_key_required, validation_failed, rate_limited, idempotency_conflict…). Chaque erreur porte error.type, le code HTTP et un message en français.
| Code | HTTP | Type | Message |
|---|---|---|---|
invalid_json | 400 | invalid_request | Le corps de la requête doit être un objet JSON valide. |
request_too_large | 413 | invalid_request | Le corps de la requête est trop lourd. |
invalid_idempotency_key | 400 | invalid_request | La clé d'idempotence doit contenir 1 à 128 caractères (lettres, chiffres, - et _). |
route_not_found | 404 | not_found | Cette route n'existe pas dans l'API boutique. Consultez la documentation. |
method_not_allowed | 405 | invalid_request | Cette méthode HTTP n'est pas acceptée sur cette route. |
missing_api_key | 401 | authentication_error | Clé API absente : envoyez l'en-tête Authorization: Bearer <clé secrète>. |
invalid_api_key | 401 | authentication_error | La clé API est inconnue ou n'est plus active. Vérifiez la clé dans Développeurs › Clés API & MCP. |
invalid_mcp_key | 401 | authentication_error | La clé MCP du compte est inconnue ou a été révoquée. Régénérez-la dans le portail (Développeurs › Clés API & MCP › Clé MCP du compte). |
service_not_found | 403 | permission_denied | Ce service n'appartient pas au compte de la clé MCP : indiquez son identifiant dans l'en-tête X-CashChap-Service. |
secret_key_required | 403 | permission_denied | L'API boutique exige la clé SECRÈTE du service (SKLIVE_…), côté serveur uniquement. |
live_key_required | 403 | permission_denied | La boutique est un objet Live : utilisez la clé secrète LIVE du service, jamais la clé Sandbox. |
account_unavailable | 403 | permission_denied | Le compte de ce service est indisponible (supprimé ou suspendu). Contactez le support CashChap. |
service_inactive | 403 | permission_denied | Ce service n'existe pas ou a été désactivé. |
account_not_activated | 403 | permission_denied | L'identité du promoteur doit être vérifiée (dossier d'activation validé) pour ouvrir ou publier une boutique. |
rate_limited | 429 | rate_limited | Trop de requêtes. Réessayez dans quelques instants. |
request_in_progress | 409 | conflict | Une requête avec cette clé d'idempotence est encore en cours. Réessayez dans une seconde. |
idempotency_conflict | 409 | conflict | Cette clé d'idempotence a déjà servi pour une autre requête. |
validation_failed | 422 | validation_error | La requête contient des champs invalides. |
confirmation_required | 422 | validation_error | Cette action est irréversible : renvoyez-la avec "confirm": true. |
internal_error | 500 | api_error | Une erreur interne est survenue. Réessayez dans un instant. |
storefront_feature_disabled | 503 | service_unavailable | Les boutiques ne sont pas encore ouvertes sur la plateforme CashChap. |
storefront_not_found | 404 | not_found | Ce service n'a pas encore de boutique : créez-la avec POST /v2/boutique. |
storefront_already_exists | 409 | conflict | Ce service a déjà une boutique : modifiez-la avec PATCH /v2/boutique. |
storefront_limit_reached | 409 | conflict | Votre compte a atteint le nombre maximal de boutiques. |
storefront_not_publishable | 409 | conflict | Ajoutez au moins un article actif avant de publier la boutique. |
storefront_suspended_by_team | 403 | permission_denied | La boutique a été suspendue par l'équipe CashChap : contactez le support pour la remettre en ligne. |
slug_change_too_soon | 409 | conflict | L'adresse ne peut être changée qu'une fois par 30 jours. |
theme_unknown | 422 | validation_error | Thème inconnu : consultez GET /v2/boutique/themes. |
category_not_found | 404 | not_found | Catégorie introuvable dans cette boutique. |
category_limit_reached | 409 | conflict | Le catalogue est limité à 30 catégories. |
category_name_taken | 409 | conflict | Une catégorie porte déjà ce nom (ou un nom trop proche). |
article_not_found | 404 | not_found | Article introuvable dans cette boutique. |
article_limit_reached | 409 | conflict | Le catalogue a atteint le nombre maximal d'articles (limite de la plateforme). |
featured_limit_reached | 409 | conflict | Six articles au plus peuvent être mis en avant. Retirez-en un d'abord. |
photo_not_found | 404 | not_found | Photo introuvable dans cette boutique. |
photo_limit_reached | 409 | conflict | Limite de photos par article atteinte. |
media_limit_reached | 409 | conflict | Limite de médias par article atteinte (photos et vidéos ensemble). |
video_limit_reached | 409 | conflict | Limite de vidéos par article atteinte. |
media_not_found | 404 | not_found | Média introuvable sur cet article. |
invalid_image | 422 | validation_error | L'image n'a pas pu être lue ou traitée. |
malicious_file_rejected | 422 | validation_error | Fichier refusé : son nom ou son contenu est suspect. Ce refus est inscrit dans votre journal d'activité. |
remote_image_refused | 422 | validation_error | Cette adresse d'image n'est pas acceptée. |
remote_download_disabled | 403 | permission_denied | Le téléchargement d'images par adresse est fermé : envoyez l'image en base64. |
demo_universe_unknown | 422 | validation_error | Univers de démonstration inconnu. |
page_type_unknown | 404 | not_found | Type de page inconnu : about, delivery ou contact. |
order_not_found | 404 | not_found | Commande introuvable dans cette boutique. |
order_not_cancellable | 409 | conflict | Cette commande ne peut plus être annulée. |
delivery_state_invalid | 409 | conflict | Cette étape de livraison n'est pas possible pour cette commande. |
message_not_found | 404 | not_found | Message introuvable dans cette boutique. |
messages_unavailable | 503 | service_unavailable | Les messages de la page Contact sont momentanément indisponibles. |
message_reply_impossible | 422 | validation_error | Impossible de répondre à ce message par e-mail. |
email_not_sent | 503 | service_unavailable | L'e-mail n'a pas pu partir. Réessayez dans un instant. |
ai_unavailable | 503 | service_unavailable | L'assistance IA n'est pas disponible sur la plateforme pour le moment. |
ai_quota_exceeded | 429 | rate_limited | Quota d'assistance IA atteint pour aujourd'hui. Réessayez demain. |
ai_model_failed | 502 | provider_error | L'assistant IA n'a pas répondu : les textes actuels sont conservés. Réessayez dans un instant. |
analysis_not_found | 404 | not_found | Analyse de photos introuvable dans cette boutique. |
analysis_not_ready | 409 | conflict | Cette analyse n'est pas prête à être confirmée. |
analysis_no_photo | 422 | validation_error | Aucune photo exploitable dans cet envoi. |
generation_not_found | 404 | not_found | Génération d'articles introuvable dans cette boutique. |