> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d'ensemble des catalogues

> Choisissez entre les snapshots complets et les modifications granulaires rapides.

L’API Catalogues permet à un POS, un middleware ou un système de restaurant de publier et maintenir le menu utilisé par Chataigne.

L’identité d’un catalogue est limitée à l’établissement. Vous fournissez les identifiants exposés dans `id`, qui restent stables pendant les mises à jour. Les mêmes IDs de catalogue et de produit peuvent être réutilisés dans un autre établissement ; un catalogue peut aussi être rattaché à plusieurs établissements sans rendre son ID public global.

La V1 liste et gère tous les catalogues rattachés à l’établissement autorisé, y compris ceux synchronisés par un POS ou créés dans le dashboard. L’origine du catalogue reste privée et ne le rend pas accessible en lecture seule. Les imports complets POS et API sont sérialisés ; si les deux systèmes écrivent dans le même catalogue, la dernière écriture validée l’emporte. La suppression d’un catalogue rattaché à plusieurs établissements est refusée afin qu’une requête limitée à un établissement ne supprime jamais le menu d’un autre.

## Choisir un mode d’écriture

| Besoin                                                                    | Opération                                               | Comportement                                      |
| ------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------- |
| Publier ou réconcilier le menu complet                                    | `PUT /v1/locations/{location_id}/catalogs/{catalog_id}` | Remplacement autoritaire asynchrone               |
| Choisir le menu utilisé par l’IA                                          | `PUT /v1/locations/{location_id}/active_catalog`        | Sélection immédiate pour l’établissement          |
| Modifier une catégorie, un produit, un groupe, un modifier ou une formule | `POST`, `PATCH` ou `DELETE` de la ressource             | Écriture ciblée immédiate                         |
| Lire le menu actuel                                                       | `GET` du catalogue ou de la ressource                   | Retourne les IDs publics, jamais les SKU internes |

Utilisez un [snapshot complet](/fr/catalogs/full-snapshot-sync) pour les imports initiaux et les synchronisations POS périodiques. Utilisez les [modifications granulaires](/fr/catalogs/granular-updates) pour changer rapidement un prix, un nom, une relation ou un article entre deux imports complets.

Un établissement peut contenir plusieurs catalogues, mais l’IA prend les commandes depuis un seul catalogue actif. Suivez le guide [Sélectionner le catalogue actif](/fr/catalogs/active-catalog) pour remplacer la ressource singleton `active_catalog` avec le `catalog_id` public et limité à l’établissement une fois le catalogue créé. La réponse renvoie cet ID public ; Chataigne conserve l’ID privé en interne.

<Info>
  Les snapshots complets et les imports POS utilisent le même moteur Chataigne de comparaison et de
  persistance. Les modifications granulaires ne comparent pas le catalogue complet : elles résolvent
  l’`id` demandé dans son parent et ne mettent à jour que cette ressource.
</Info>

## Permissions

La lecture requiert `catalog.read`. La création, la synchronisation et les mises à jour requièrent `catalog.write`. La suppression requiert `catalog.delete`.

## Périmètre de la V1

La V1 gère les catégories, produits, groupes de modifiers, modifiers et formules. Les produits contiennent directement leur prix de base, les IDs de leurs groupes, leur état opérationnel, leurs prix conditionnels et leurs règles de disponibilité. Le SKU interne de Chataigne n’apparaît jamais dans les requêtes ou réponses.

Les produits, modifiers et formules utilisent les mêmes champs opérationnels. `disabled: true` masque la ressource et empêche sa commande. `out_of_stock: true` la conserve visible mais temporairement indisponible. `restrictions` définit les fenêtres de vente et types de service ; `price_overrides` définit les prix conditionnels. Les produits exposent également `bundle_only` et un champ d’entrée `order` optionnel.

Les promotions, paramètres de catalogue autres que la sélection du catalogue actif, catégories principales ou masquées, indicateurs de meilleure vente, taxes, informations de colis, métadonnées provider et produits multi-SKU ne sont pas gérés par cette version.