Passer de la version 2 à la version 2.1 de Content API

En mars 2019, nous avons lancé la version 2.1 de Content API for Shopping, et en avril 2021, nous avons annoncé que l'intégration de la version 2 s'arrêterait le 30 septembre 2021. La version 2 a été abandonnée. Veuillez migrer immédiatement vers la version 2.1.

Migrer votre application

La migration de la version 2 vers la version 2.1 implique de mettre à jour vos URL de point de terminaison pour appeler la nouvelle version 2.1 et de modifier vos applications de sorte qu'elles tiennent compte des modifications destructives introduites dans la version 2.1.

Mettre à jour vos appels d'API pour utiliser les points de terminaison de la version 2.1

Pour effectuer des appels vers la version 2.1, mettez à jour vos requêtes afin qu'elles utilisent les nouveaux points de terminaison de la version 2.1.

Par exemple, pour appeler la méthode products.get avec la version 2, vous deviez utiliser :

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

Pour la version 2.1, mettez à jour l'URL comme suit :

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

Pour en savoir plus sur les services et les points de terminaison de la version 2.1, consultez la documentation de référence de l'API.

Apporter les modifications requises

En plus de mettre à jour les URL pour vos appels d'API, vous devez également mettre à jour votre application pour qu'elle tienne compte de plusieurs modifications destructives introduites dans la version 2.1. Consultez les sections suivantes et mettez à jour votre application si nécessaire.

1. Mettre à jour les intégrations au service inventory

Le service inventory de la version 2 a été supprimé. Les fonctionnalités équivalentes de la version 2.1 suivantes sont disponibles :

  • Utilisez de nouveaux flux supplémentaires ou products.update pour mettre partiellement à jour les produits. Les mises à jour sont possibles pour tous les champs de produit modifiables, y compris tous les champs précédemment mis à jour avec inventory.set (à l'exception des champs exclusifs à localinventory). Consultez Migrer vers les flux supplémentaires pour en savoir plus.

  • Utilisez le nouveau service localinventory pour mettre à jour les produits en magasin.

2. Mettre à jour les appels au service accounts

  • Les appels à la méthode accounts.update dans la version 2.1 écrasent complètement la ressource accounts, au lieu de ne mettre à jour que les champs inclus dans la requête. Pour éviter de supprimer des champs de la ressource accounts, mettez à jour vos requêtes d'appel de façon à inclure tous les champs.

  • Le paramètre reviewsUrl a été supprimé.

  • L'état inactive des liens a été supprimé pour adsLinks, googleMyBusinessLink et youtubeChannelLinks.

3. Mettre à jour les appels au service products

  • Les attributs personnalisés ne contiennent plus de type ni d'unité. À la place, les unités doivent être ajoutées à la valeur et les types sont automatiquement détectés.

  • Le champ répété productTypes remplace à la fois productType et additionalProductTypes.

  • Les champs répétés includedDestinations et excludedDestinations remplacent le champ répété destinations.

  • Les champs suivants liés à AdWords ont été renommés :

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • Les champs suivants ont été supprimés :

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • Le paramètre includeInvalidInsertedItems a été supprimé. Dans la version 2.1, tous les produits sont renvoyés par défaut.

  • Un délai de quelques minutes est désormais nécessaire avant qu'un produit inséré ne puisse être récupéré via products.get ou products.list.

  • La valeur offerId affichée n'est plus garantie comme étant la valeur offerId saisie. La version 2.1 coupe les espaces de début et de fin dans le fichier offerId, et fusionne plusieurs espaces blancs en un seul. Cette modification n'a pas d'incidence sur les valeurs offerId qui respectent la syntaxe offerId recommandée.

  • Les prix sont désormais validés avant l'insertion du produit. Seuls les caractères suivants sont autorisés dans la chaîne de valeur : +, - et ., ainsi que les chiffres (ex. : 0-9). Les virgules ne sont plus acceptées.

  • Les réponses d'un appel products.insert ou products.update ne contiennent que les attributs suivants :

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • L'option includeAttributes de la version 2 est obsolète. Utilisez plutôt products.get avec ProductId pour afficher toutes les informations produit.

4. Mettre à jour les appels au service productstatuses

  • L'attribut product a été supprimé, de même que le paramètre includeAttributes. Pour récupérer les attributs du produit correspondant à un état, utilisez le service products et transmettez la valeur du nouveau champ productId.

  • Le paramètre includeInvalidInsertedItems a été supprimé. Le champ productId de chaque produit est désormais renvoyé, que le produit soit valide ou non.

  • Les champs intention, approvalStatus et approvalPending dans destinationStatuses ont été remplacés par le champ status, qui correspond à une chaîne pouvant être approved, disapproved ou pending.

  • dataQualityIssues a été remplacé par itemLevelIssues.

5. Mettre à jour les appels au service datafeeds

  • Les champs cibles suivants ont été remplacés :

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations et excludedDestinations

  • Les flux de données avec contentType = "product inventory update" ont été supprimés.

6. Mettre à jour les appels aux services orders et TestOrders

  • Dans la version 2.1, les appels ne doivent pas inclure de données fiscales, car celles-ci sont calculées automatiquement. Si la commande exécutée dans un État où une loi sur l'équité du marché (Marketplace Fairness Act) ou une loi similaire est en vigueur, les appels comprenant des données fiscales échouent. Si la commande est exécutée dans un État non soumis à ce type de législation, les taxes sont calculées en fonction des paramètres configurés dans Merchant Center. Si aucun paramètre n'est défini, la taxe calculée est égale à 0.

  • Les champs InStoreRefundLineItem et ReturnRefundLineItem amountPretax et amountTax ont été remplacés respectivement par priceAmount et taxAmount. Le champ priceAmount peut être hors taxes ou TTC selon le lieu de la commande.

  • Les champs ShipLineItem carrier, shipmentId et trackingId de la requête ont été déplacés vers shipmentInfos.

  • billingAddress et predefinedBillingAddress sont désormais des champs de premier niveau dans orders et TestOrder, respectivement.

  • customer.explicitMarketingPreference a été remplacé par customer.marketingRightsInfo.

  • Le champ netAmount a été divisé en netPriceAmount et netTaxAmount.

  • shippingOption a été remplacé par lineItems[].shippingDetails.

  • Les champs CancelLineItem amount, amountPretax et amountTax de la requête ont été supprimés. Le montant remboursé est désormais calculé automatiquement.

  • CustomBatch a été supprimé.

  • Refund a été supprimé. Utilisez refundOrder ou refundItem à la place.

  • Le champ paymentMethod a été supprimé.

  • Les méthodes orders.returnlineitem et orders.refund de la version 2 sont remplacées par orderreturns.creatOrderReturn et orderreturns.process.

  • Les champs customer.email, channelType et lineItem.product.channel ont été supprimés.

  • Le champ promotions a été supprimé du service TestOrder, et son format a été modifié dans Order.

7. Mettre à jour les appels au service orderinvoice

  • Les champs amountPretax et amountTax ont été remplacés respectivement par priceAmount et taxAmount. Le champ priceAmount peut être hors taxes ou TTC selon le lieu de la commande.

  • Les soldes (marchand, client et Google) ont été supprimés de invoiceSummary et des champs liés aux promotions.

8. Supprimer des fonctionnalités non incluses dans la version 2.1

Plusieurs autres fonctionnalités ont été supprimées dans la version 2.1 de Content API. Consultez la liste suivante et mettez à jour votre application si nécessaire :

  • Le format XML n'est plus accepté. Pour en savoir plus sur le passage au format JSON, consultez l'article Arrêt de la compatibilité du format XML dans Content API for Shopping.

  • Le paramètre dryRun a été supprimé. Cette modification s'applique à tous les appels d'API.

  • Toutes les méthodes HTTP BATCH ont été supprimées. Utilisez plutôt customBatch.

  • La méthode patch a été supprimée des services suivants :

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • Le service orderpayments a été supprimé.

Tester la migration

Pour en savoir plus sur le test des modifications apportées à vos applications après la migration vers la version 2.1, consultez la page Tester Content API for Shopping. Si vous rencontrez des problèmes lors du test de vos mises à jour, vous pouvez publier un post à ce sujet sur le forum de Content API.

Modifications supplémentaires dans la version 2.1

En plus des modifications nécessitant des mises à jour, la version 2.1 introduit également plusieurs nouvelles fonctionnalités et modifications non destructives :

  • Nouveaux services :

    • Le nouveau service localinventory vous permet de mettre à jour les produits en magasin (il remplace le service inventory dans la version 2).

    • Le nouveau service orderreturns facilite la gestion du programme Acheter sur Google (anciennement appelé Shopping Actions) en vous permettant de traiter les retours sans avoir à utiliser le service orders.

  • Avec les flux supplémentaires, vous pouvez effectuer des mises à jour partielles des produits.

  • Modifications supplémentaires apportées au service products :

    • Les requêtes products.insert ne renvoient plus d'erreurs ni d'avertissements non fatals. Cela vous permet d'insérer des produits et d'effectuer des mises à jour ultérieures pour résoudre des problèmes via les règles de flux dans Merchant Center, comme vous le faites pour les flux gérés en dehors de Content API.

    • products.update a été ajouté pour que vous puissiez mettre à jour un ensemble de champs de produit de votre choix. Pour plus d'informations sur son utilisation, consultez le guide.

    • Les valeurs non valides pour les attributs suivants ne déclenchent plus d'erreurs d'insertion et sont renvoyées en tant que itemLevelIssues par le service productstatus :

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • Les attributs personnalisés sont désormais récursifs. De ce fait, le recours aux groupes personnalisés n'est plus nécessaire.

    • Les attributs personnalisés disposent désormais d'un champ groupValues en plus du champ d'origine value. Un seul de ces champs doit être défini.