Flux par fichier vs flux par API — ACP

Les deux méthodes d'intégration du flux produit ne sont pas concurrentes mais complémentaires. Le fichier livre un instantané complet, traité comme source de vérité, à cadence recommandée d'au moins une fois par jour. L'API met à jour des produits ou des promotions individuellement, en continu, et reste la seule voie disponible pour les promotions.

La recommandation par défaut combine les deux — le fichier pour le catalogue de référence, l'API pour les mises à jour intrajournalières. Exception : un catalogue de petite taille, pour lequel l'API seule peut suffire à tout couvrir, intégralité comme mises à jour.

Deux représentations distinctes du même catalogue

Les deux méthodes n'exposent pas les données produit de la même façon. Le fichier utilise un format délimité (parquet, jsonl.gz, csv.gz, tsv.gz) où le prix s'écrit en chaîne composite « montant devise » (price, sale_price). L'API expose des objets JSON imbriqués où le prix se décompose en amount et currency séparés, avec price désignant le prix de vente actif et list_price le prix de référence avant remise. Aucune table de correspondance officielle ne relie explicitement ces deux paires de champs de prix ; un marchand qui combine les deux méthodes doit donc établir lui-même ce mapping, sans certitude publiée sur la correspondance exacte entre price/sale_price (fichier) et price/list_price (API).

La suppression d'un produit suit aussi des logiques différentes : côté fichier, is_eligible_search=false ou une simple absence du prochain instantané suffisent ; côté API, aucun mécanisme de suppression complète n'est documenté au-delà de la mise à jour de champs existants.

Mise en pratique

1. Retenir la combinaison fichier quotidien + API intrajournalière comme point de départ par défaut, sauf catalogue de petite taille.
2. Prévoir l'API dès que des promotions doivent être exposées, quelle que soit la méthode choisie pour le catalogue.
3. Documenter en interne la correspondance retenue entre les champs de prix des deux schémas, faute de référence officielle publiée, pour éviter toute divergence entre les deux flux d'un même catalogue.

Erreurs à éviter

Supposer que l'API peut totalement remplacer le fichier pour un grand catalogue, sans instantané de référence régulier, va à l'encontre de la recommandation par défaut, réservée aux flux de petite taille. Assumer une correspondance terme à terme entre les champs de prix des deux schémas sans la vérifier expose à des écarts de prix affichés entre les deux méthodes.

Ce qu'il faut retenir

Le choix entre fichier et API n'est pas binaire : la combinaison des deux, fichier pour la référence et API pour la finesse, est la configuration recommandée par défaut. La vraie vigilance porte sur la représentation des données, structurellement différente d'une méthode à l'autre, en particulier sur les champs de prix — un point qui reste à vérifier faute de correspondance officielle publiée.