Intégrer un flux produit par API — ACP

L'intégration par API gère le flux produit via trois surfaces REST complémentaires — Feeds, Products, Promotions — appelées avec les mêmes en-têtes et sous la même authentification. Elle permet des mises à jour partielles et continues, là où l'intégration par fichier ne livre qu'un instantané complet à cadence régulière ; c'est aussi la seule voie disponible pour les promotions.

Authentification et en-têtes communs

Chaque requête porte une clé API dans Authorization (Bearer api_key_123), une locale dans Accept-Language, des informations client dans User-Agent, une clé d'idempotence dans Idempotency-Key, un identifiant de traçage dans Request-Id, un type de contenu (application/json), un horodatage RFC 3339 dans Timestamp, et une version d'API (par exemple 2025-09-12). La réponse reprend Idempotency-Key et Request-Id de la requête — un mécanisme cohérent avec le modèle d'upsert des surfaces Products et Promotions, pensé pour permettre un rejeu sûr d'une requête déjà traitée.

Créer et lire un flux

POST /product_feeds crée un flux à partir d'un target_country optionnel et retourne son id, sa target_country et son updated_at ; GET /product_feeds/{id} relit ces mêmes métadonnées, avec une réponse 404 si le flux est introuvable. L'id retourné sert ensuite de paramètre de chemin à tous les endpoints Products et Promotions.

Mise en pratique

1. Créer le flux via POST /product_feeds et conserver son id.
2. Authentifier chaque appel suivant avec la même clé API et transmettre systématiquement Idempotency-Key sur les requêtes sensibles au rejeu.
3. Combiner avec l'intégration par fichier pour le catalogue de référence si le volume le justifie, en réservant l'API aux mises à jour intrajournalières et aux promotions.

Erreurs à éviter

Omettre Idempotency-Key sur des appels réémis automatiquement expose à un risque de duplication d'effet en cas de retry, même si la sémantique exacte de reprise n'est pas confirmée dans le détail par la documentation disponible. Traiter les endpoints Feeds comme suffisants pour gérer le catalogue est une autre erreur : cette surface ne couvre que la création et la lecture du flux, pas les produits ni les promotions qu'il contient.

Ce qu'il faut retenir

L'intégration par API se distingue par sa granularité : elle agit produit par produit ou promotion par promotion, sous la même authentification pour les trois surfaces. Elle complète naturellement la méthode fichier plutôt que de la remplacer, et reste la seule voie pour exposer des promotions.