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 juillet 2020, nous avons annoncé l'arrêt de la version 2 à partir du 29 mars 2021. À compter de cette date, toutes les requêtes adressées à la version 2 de Content API échoueront. Ce guide explique comment mettre à jour votre application pour qu'elle soit compatible avec la version 2.1. Nous vous recommandons de procéder à la migration dès que possible afin d'éviter que votre application ne soit affectée.

Migrer votre application

La migration de la version 2 vers la version 2.1 implique la mise à jour de vos URL de point de terminaison pour appeler la nouvelle version 2.1 ainsi que la modification de 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é et remplacé par deux nouvelles fonctionnalités dans la version 2.1 :

  • Utilisez de nouveaux flux supplémentaires pour les mises à jour partielles des données produit.
  • Utilisez le nouveau service localinventory pour les mises à jour des données produit 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é.

  • 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 ne contiennent désormais que les attributs suivants :

    • channel
    • contentLanguage
    • id
    • offerId
    • targetCountry

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é.

  • ReturnLineItem a été supprimé. Utilisez returnRefundLineItem à la place, sans indiquer de montant de remboursement.

  • 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 permet de mettre à jour les données produit en magasin (à la place du service inventory dans la version 2).

    • Le nouveau service orderreturns facilite la gestion du programme Acheter sur Google (anciennement appelé Shopping Actions) en autorisant le traitement des retours sans avoir à utiliser le service orders.

  • Les flux supplémentaires vous permettent d'effectuer des mises à jour partielles des données produit.

  • 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.

    • 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.