# agentic-commerce-api

API de **présentation catalogue** et de **devis configurable** Fulfiller, destinée aux agents IA et au
chatbot. Particularité : un produit Fulfiller n'est pas un SKU à prix figé mais un **espace de
configuration** (format, support, grammage, quantité, finition, délai) dont le prix est **calculé**.

## Endpoints

- `GET /catalog/search?q=&limit=` — recherche de produits cotables (renvoie `productId`, `sku`, prix d'appel affiché par le site, indicatif). Un ou deux mots produit, pas une phrase.
- `GET /catalog/resolve?sku=`, `?url=` **ou** `?productId=` — identité EXACTE → `productId`, SKU, nom, liens. Si vous arrivez d'une page produit, son SKU est déclaré dans le JSON-LD de la page : passez par ici plutôt que par une recherche approximative.
- `GET /catalog/product?sku=`, `?url=` **ou** `?productId=` — fiche produit (descriptions, points clés, FAQ, contraintes de fichier, visuels, `videos`). Aucun prix : ceux écrits dans les textes PIM sont souvent périmés.
- `GET /products/{id}/config` — espace de configuration d'un produit (options et valeurs disponibles). Porte aussi l'`url` de la page produit quand elle est résoluble.
- `POST /products/{id}/validate` — résout une sélection (tolérante) et vérifie sa commandabilité par une sonde de cotation interne (aucun prix renvoyé) → sélection résolue, options activables, alertes. Une quantité soumise hors de toute plage déclarée ressort en alerte `QUANTITY_OUT_OF_RANGE` severity `error` — c'est exactement ce que `/quote` refusera en 400 sur la même sélection.
- `POST /products/{id}/quote` — devis pour une sélection (prix HT, devise, délai, promo). Prix à annoncer : `devis.finalPriceHt` (promotion déduite).
- `POST /products/{id}/quote/pivot` — grille de prix par palier de quantité, même règle que `/quote` palier par palier (`quotedQuantity` quand le palier est ramené au pas commandable).
- `POST /checkout` — crée un panier anonyme (id-capacité), avec des lignes initiales optionnelles.
- `GET /checkout/{id}` — lit un panier (snapshot figé, jamais re-coté à la lecture).
- `PATCH /checkout/{id}` — modifie un panier (retraits, changements de quantité, ajouts).
- `DELETE /checkout/{id}` — supprime définitivement un panier (204 ; 404 si inconnu ou expiré).

## Connecteur MCP

`POST https://www.fulfiller.com/agenticopenapi/mcp` — serveur **MCP** (Model Context Protocol), transport Streamable HTTP,
stateless et sans authentification. Collez cette URL dans un client compatible (connecteurs
Claude, mode développeur ChatGPT, Claude Code, IDE) pour installer le catalogue et le devis
Fulfiller comme outils. Les outils exposés enveloppent exactement les endpoints ci-dessus.

Contrat machine : `https://www.fulfiller.com/agenticopenapi/openapi.json` (OpenAPI 3.1). Statut : `https://www.fulfiller.com/agenticopenapi/health`.