Schéma des produits via l'API — ACP

Côté API, un produit du flux se lit et se met à jour via GET/PATCH /product_feeds/{id}/products, sous la forme d'objets JSON imbriqués — un Product contenant un ou plusieurs Variant. GET retourne target_country et le tableau products ; PATCH upserte des produits appariés par id, les produits non inclus restant inchangés, avec un objet d'acceptation (id, accepted) en retour et 404 si le flux est introuvable.

Cette structure diffère de celle du fichier plat, où le même domaine produit s'écrit à plat, une ligne par variante — voir Flux par fichier vs flux par API — ACP pour l'arbitrage entre les deux.

Le produit et ses variantes

Un Product ne porte que peu de champs propres — id (identifiant global stable, requis), title, description, url, media (assets au niveau produit) — l'essentiel de l'information vivant au niveau Variant : id et title y sont les deux seuls champs requis, tout le reste étant optionnel au sens du schéma même si son absence dégrade l'affichage. Une variante porte son propre prix (price, prix de vente actif ; list_price, prix de référence avant remise ; unit_price pour le prix unitaire), sa disponibilité (availability), ses codes-barres (barcodes), ses catégories (categories), ses états applicables (condition), ses dimensions d'option visibles comme couleur ou taille (variant_options), ses assets (media, la première entrée servant d'image principale) et son vendeur (seller).

Type	Champs principaux
Description	Au moins un de plain, html, markdown.
Availability	available (booléen), status (in_stock, backorder, preorder, out_of_stock, discontinued).
Price	amount (unités mineures ISO 4217, requis), currency (ISO 4217 trois lettres, requis).
UnitPrice	amount, currency, measure (Measure), reference (ReferenceMeasure) — tous requis.
Barcode	type, value — requis.
Media	type, url — requis ; alt_text, width, height — optionnels.
VariantOption	name (couleur, taille...), value — requis.
Category	value (requis), taxonomy (optionnel — google_product_category, shopify, merchant).
Seller	name (optionnel), links (Link[], optionnel).
Link	type (requis — privacy_policy, terms_of_service, refund_policy, shipping_policy, faq), url (requis), title (optionnel).
Condition	Tableau de chaînes (new, secondhand...), plusieurs valeurs possibles.

Mise en pratique

1. Construire chaque Variant avec un id stable et distinct de celui du Product parent, conformément aux bonnes pratiques de modélisation des variantes.
2. Envoyer par PATCH uniquement les produits réellement modifiés — le modèle d'upsert préserve les autres.
3. Documenter la correspondance retenue entre price/list_price de ce schéma et price/sale_price du schéma de fichier plat avant de combiner les deux méthodes sur un même catalogue, faute de table de correspondance officielle publiée.

Erreurs à éviter

Retransmettre l'intégralité d'un Product ou d'un Variant alors qu'une mise à jour partielle suffit va à l'encontre du modèle d'upsert par id — même si le comportement exact pour la mise à jour partielle d'un sous-objet imbriqué (par exemple availability seul) n'est pas précisé dans le détail. Confondre price (prix de vente actif, potentiellement déjà remisé) et list_price (prix de référence) est une autre source d'erreur, à ne pas transposer sans vérification vers les champs de même nom du schéma de fichier plat.

Ce qu'il faut retenir

Le schéma API privilégie la granularité : chaque variante porte son propre prix, sa propre disponibilité, ses propres assets, mis à jour indépendamment par upsert. Sa structure en objets imbriqués n'est pas interchangeable telle quelle avec le fichier plat — la correspondance des champs de prix entre les deux reste à établir au cas par cas.