API vitrine v2

Gérez votre vitrine 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 vitrine 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), côté serveur uniquement. La vitrine vend toujours en mode Live : une clé SKSANDBOX_… répond 403 live_key_required, une clé publique, de terminal ou de session 403 secret_key_required.
• Clé absente : 401 missing_api_key (en-tête WWW-Authenticate) ; clé inconnue, mal formée ou désactivée : 401 invalid_api_key. La clé est comparée en temps constant, jamais journalisée.
• La vitrine est celle du service de la clé (une par service). Un service sans vitrine répond 404 storefront_not_found avec details.can_create ; créez-la avec POST /v2/vitrine.
• Toute écriture est inscrite dans Compte › Journal d'activité du portail (action « VITRINE (API) », mode Live, adresse IP et User-Agent de l'appel).

Réponses, pagination, idempotence, débit

HTTP/1.1 200 OK
CashChap-Version: 2.6.0
CashChap-Vitrine-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-vitrine#erreurs"
  }
}

• Enveloppes identiques à l'API v2 : {"data", "meta"} ou {"error"}, jamais de champ success ; X-Request-Id reprend meta.request_id. Les champs sont en anglais snake_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, code unknown_field) ; un corps qui n'est pas un objet JSON répond 400 invalid_json.
• Versions : CashChap-Version donne la version de la norme v2 publiée (2.6.0), CashChap-Vitrine-Version celle 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_cursor de la page précédente ; meta.has_more, meta.total.
• Idempotence des créations (POST /v2/vitrine, catégories, articles, photos, analyses, génération, réponse à un message) : en-tête Idempotency-Key facultatif (1 à 128 caractères : lettres, chiffres, -, _). Même clé et même corps : même réponse, en-tête Idempotent-Replayed: true ; même clé et corps différent : 409 idempotency_conflict ; requête encore en cours : 409 request_in_progress. Mémoire : 24 h.
• Débit, par clé et par minute : 300 lectures, 60 écritures, 10 lancements IA. Au-delà : 429 rate_limited avec Retry-After.
• Actions irréversibles (zone Danger, suppression groupée, suppression des brouillons IA) : le corps doit porter "confirm": true, sinon 422 confirmation_required.

La vitrine

curl -X POST https://cashchap.com/v2/vitrine \
  -H "Authorization: Bearer $CASHCHAP_CLE_SECRETE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: creation-vitrine-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 vitrine : 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

Articles, variantes, photos

curl -X POST https://cashchap.com/v2/vitrine/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

Commandes

Messages de la page Contact

Assistance IA

Disponible quand CashChap l'active (GET /v2/vitrine/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.

# 1. Lancer l'analyse (202)
curl -X POST https://cashchap.com/v2/vitrine/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/vitrine/analyses/ANALYSE_ID -H "Authorization: Bearer $CASHCHAP_CLE_SECRETE"

# 3. Confirmer les brouillons corrigés (201)
curl -X POST https://cashchap.com/v2/vitrine/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 vitrine_* pour les assistants (Claude Desktop, Claude Code, Cursor…) : vitrine_voir, vitrine_creer, vitrine_modifier, vitrine_publier, vitrine_categories_*, vitrine_articles_*, vitrine_photos_*, vitrine_livraison_*, vitrine_pages_*, vitrine_commandes_*, vitrine_messages_*, vitrine_analyse_*, vitrine_generation_*, vitrine_referencement_*. Il utilise la même clé secrète que les outils de paiement (CASHCHAP_API_KEY, mode live), appelle CASHCHAP_PORTAIL_URL (https://cashchap.com par défaut) et exige une confirmation explicite pour les actions destructrices. Variable CASHCHAP_MCP_VITRINE : true (gestion complète, défaut), lecture (consultation seule) ou false.

Codes d'erreur

Codes propres à l'API vitrine, 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.