Intégrer un flux produit par fichier (SFTP) — ACP

L'intégration par fichier livre à OpenAI, par push SFTP, un instantané complet du catalogue traité comme source de vérité — à cadence recommandée d'au moins une fois par jour. C'est la méthode de référence du flux produit, respectant le schéma de fichier plat documenté par OpenAI.

Formats acceptés : parquet (préféré, idéalement compressé ztsd), jsonl.gz, csv.gz, tsv.gz, en UTF-8. Le nom de fichier doit rester stable — écrasé à chaque mise à jour plutôt que renommé — et, en cas de fragments multiples, le même jeu de fragments doit être conservé et remplacé à l'identique à chaque envoi ; dimensionnement recommandé : jusqu'à 500 000 articles par fragment, fichiers cibles sous ~500 Mo.

Retirer un produit

Deux options retirent un produit du flux : marquer is_eligible_search=false, ou simplement l'omettre du prochain instantané complet. Dans ce second cas, l'absence dans l'instantané suivant suffit à le retirer, sans action explicite supplémentaire — une conséquence directe du modèle « instantané complet » qui distingue cette méthode de la mise à jour partielle de l'API.

Valider avant de passer en volume

La validation se fait en trois temps : un petit échantillon d'environ 100 articles couvrant tous les champs requis, un contrôle qualité sur le premier instantané complet, puis un passage à l'automatisation en régime permanent une fois cette validation propre. Les échecs d'ingestion les plus courants à surveiller : champs requis manquants, noms de champs obsolètes ou hors spécification, valeurs malformées. Une ligne malformée peut être rejetée sans bloquer le traitement des autres lignes valides du même envoi.

Si plusieurs flux de marque partagent un même emplacement de dépôt, des noms de fichier préfixés par marque évitent toute ambiguïté. Un flux qui sert aussi une intégration Ads Manager est en outre soumis à une exigence d'éligibilité Ads additionnelle, documentée séparément par le guide « Ads product feeds ».

Mise en pratique

1. Préparer un échantillon d'environ 100 articles couvrant tous les champs requis du schéma.
2. Livrer ce premier échantillon par SFTP et exécuter un contrôle qualité complet.
3. Passer à l'instantané complet quotidien une fois l'échantillon validé, avec un nom de fichier stable et écrasé à chaque envoi.
4. Combiner avec l'API si des mises à jour intrajournalières ou des promotions sont nécessaires.

Erreurs à éviter

Créer un nouveau nom de fichier à chaque envoi plutôt que d'écraser le fichier stable existant rompt l'exigence de stabilité du nom. Passer directement à l'automatisation en régime permanent sans valider d'abord un échantillon puis un premier instantané complet expose à des rejets en volume évitables. Oublier l'exigence d'éligibilité Ads additionnelle quand le même flux sert aussi une intégration Ads Manager est une autre source d'erreur fréquente.

Ce qu'il faut retenir

La méthode fichier fonctionne comme un pipeline d'instantanés, pas comme un flux d'événements : chaque envoi remplace intégralement l'état précédent, ce qui simplifie la gestion des suppressions mais impose une cadence régulière et une validation progressive avant tout passage en automatisation.