Le snapshot complet est le mécanisme recommandé pour l’import initial et la synchronisation périodique d’une intégration POS.
catalog_id est votre identifiant et n’est unique que dans l’établissement. Il peut être réutilisé pour un autre restaurant.
Le snapshot est autoritaire. Envoyez toutes les catégories, tous les produits, groupes de
modifiers, modifiers et formules. Une entité absente d’un snapshot ultérieur réussi est supprimée.
Envoyez un tableau vide pour vider une collection.
Envoyer un snapshot
La requête nécessite un Idempotency-Key. L’ordre des tableaux devient l’ordre d’affichage. Un produit peut définir un order explicite positif ou nul ; les produits qui l’omettent sont placés après les produits explicitement ordonnés de leur catégorie, dans l’ordre du snapshot.
Le serveur valide les IDs, références, limites de sélection, prix, devise et taille avant d’accepter le traitement. Les IDs peuvent contenir des lettres, chiffres, ., _, : et -, sont limités à 128 caractères et ne peuvent plus être modifiés.
Suivre la synchronisation
Une requête valide retourne 202 Accepted, un objet catalog_sync et un en-tête Location.
Interrogez l’URL de Location jusqu’à ce que status soit succeeded ou failed. Utilisez un backoff exponentiel borné en commençant par la valeur de Retry-After. Répéter la requête avec la même clé d’idempotence et le même corps retourne la même synchronisation ; réutiliser cette clé avec un autre corps retourne un conflit.
Le dernier catalogue validé reste lisible pendant le traitement. N’envoyez un nouveau snapshot qu’après l’état terminal du précédent.
Règles de remplacement
La correspondance utilise vos IDs et conserve les relations privées de Chataigne. Le snapshot est autoritaire pour chaque champ public. Omettre description ou image_url l’efface. Omettre les champs opérationnels applique leurs valeurs sûres par défaut : disabled: false, out_of_stock: false, restrictions: [], price_overrides: [] et bundle_only: false. Des tableaux de règles vides effacent les règles existantes.
Les champs privés qui restent hors de cette version — comme l’indicateur de meilleure vente, la taxe, les informations de colis, la metadata provider, les paramètres et les promotions — sont préservés sur les entités correspondantes.
Les imports complets et l’étape de mutation en base des écritures granulaires d’un même catalogue sont sérialisés. La préparation des images d’un snapshot public reste hors de cette section critique. Les modifications granulaires ne sont pas fusionnées avec un snapshot en attente dans la V1 : une écriture granulaire validée avant l’étape de mutation du snapshot est prise en compte dans son remplacement autoritaire, tandis qu’une écriture qui atteint cette frontière après la prise du lease attend pendant une durée bornée puis est validée après lui. Si le catalogue reste occupé, la requête granulaire retourne 409 catalog_sync_lock_timeout et peut être relancée. La dernière écriture validée l’emporte. 
