Migrar da API Content v2 para a v2.1

Em março de 2019, lançamos a versão 2.1 da API Content for Shopping e, em abril de 2021, anunciamos que a v2 seria desativada em 30 de setembro de 2021. A versão v2 foi desativada. Migre para a v2.1 imediatamente.

Migrar o aplicativo

A migração da v2 para a v2.1 envolve a atualização dos URLs de endpoint para chamar as novas versões da v2.1 e a modificação dos aplicativos para considerar as mudanças incompatíveis introduzidas na v2.1.

Atualizar as chamadas de API para usar endpoints v2.1

Para fazer chamadas para a v2.1, atualize suas solicitações para usar os novos endpoints da v2.1.

Por exemplo, para chamar o método products.get com a v2, use:

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

Para a v2.1, atualize o URL para:

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

Para informações completas sobre serviços e endpoints da v2.1, consulte a Referência da API.

Faça as alterações necessárias

Além de atualizar os URLs das chamadas de API, também é necessário atualizar o aplicativo para considerar várias mudanças incompatíveis introduzidas na v2.1. Revise as seções a seguir e atualize o aplicativo conforme necessário.

1. Atualizar integrações com o serviço inventory

O serviço v2 inventory foi removido, e a funcionalidade equivalente está disponível com os seguintes recursos da v2.1:

  • Use os novos Feeds complementares ou products.update para atualizações parciais de produtos. É possível atualizar todos os campos mutáveis de produtos, incluindo todos os campos atualizados anteriormente com inventory.set (exceto aqueles exclusivos do localinventory). Consulte Migrar para feeds complementares para mais detalhes.

  • Use o novo serviço localinventory para atualizações de produtos disponíveis na loja física.

2. Atualizar chamadas para o serviço accounts

  • As chamadas para o método accounts.update na v2.1 substituem completamente o recurso accounts, em vez de apenas atualizar os campos incluídos na solicitação. Para evitar a exclusão de campos no recurso accounts, atualize suas solicitações de chamada para incluir todos os campos.

  • O reviewsUrl foi removido.

  • O status do link inactive foi removido para adsLinks, googleMyBusinessLink e youtubeChannelLinks.

3. Atualizar chamadas para o serviço products

  • Os atributos personalizados não contêm mais um tipo e uma unidade. Em vez disso, as unidades precisam ser anexadas ao valor, e os tipos devem ser detectados automaticamente.

  • O campo repetido productTypes substituiu productType e additionalProductTypes.

  • Os campos repetidos includedDestinations e excludedDestinations substituíram o campo repetido destinations.

  • Os seguintes campos relacionados ao AdWords foram renomeados:

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

  • Os seguintes campos foram removidos:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • O parâmetro includeInvalidInsertedItems foi removido. Na v2.1, todos os produtos são retornados por padrão.

  • Agora há um atraso de alguns minutos antes que um produto inserido possa ser recuperado via products.get ou products.list.

  • Não há mais garantia de que o offerId retornado seja o mesmo que o offerId de entrada. A v2.1 remove os espaços em branco no início e no fim do offerId e mescla vários caracteres de espaço em branco em um só. Essa mudança não afeta os valores de offerId que estão de acordo com a sintaxe offerId recomendada.

  • Agora os preços são validados antes da inserção do produto. Somente os seguintes caracteres são permitidos na string de valor: +, -, . e dígitos (ou seja, 0-9). As vírgulas não são mais aceitas.

  • As respostas de uma chamada products.insert ou products.update contêm apenas os seguintes atributos:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • A opção v2 includeAttributes foi descontinuada. Em vez disso, use products.get com ProductId para ver as informações completas do produto.

4. Atualizar chamadas para o serviço productstatuses

  • O atributo product foi removido, assim como o parâmetro includeAttributes. Para recuperar os atributos do produto correspondentes a um status, use o serviço products e transmita o valor do novo campo productId.

  • O parâmetro includeInvalidInsertedItems foi removido. O productId de cada produto agora é retornado, independente de o produto ser válido.

  • Os campos intention, approvalStatus e approvalPending em destinationStatuses foram substituídos por status, que é uma string que pode ser approved, disapproved ou pending.

  • dataQualityIssues foi substituído por itemLevelIssues.

5. Atualizar chamadas para o serviço datafeeds

  • Os seguintes campos de destino foram substituídos:

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

  • Os feeds de dados com contentType = "product inventory update" foram removidos.

6. Atualizar chamadas para os serviços orders e TestOrders

  • Na v2.1, as chamadas não devem incluir dados de tributos porque eles são calculados automaticamente. Se o pedido for atendido em um estado com uma lei de justiça do Marketplace (MFA, na sigla em inglês) ou semelhante, as chamadas que incluírem dados fiscais vão falhar. Se o pedido for atendido em um estado sem MFA, o tributo será calculado com base nas configurações do Merchant Center. Se não for configurado, o tributo calculado será 0.

  • Os campos InStoreRefundLineItem e ReturnRefundLineItem amountPretax e amountTax foram substituídos por priceAmount e taxAmount, respectivamente. O priceAmount pode ser antes ou depois dos tributos, dependendo da localização do pedido.

  • Os campos carrier, shipmentId e trackingId de ShipLineItem na solicitação foram movidos para shipmentInfos.

  • billingAddress e predefinedBillingAddress agora são campos de nível superior em orders e TestOrder, respectivamente.

  • customer.explicitMarketingPreference foi substituído por customer.marketingRightsInfo.

  • O campo netAmount foi dividido em netPriceAmount e netTaxAmount.

  • shippingOption foi substituído por lineItems[].shippingDetails.

  • Os campos CancelLineItem amount, amountPretax e amountTax na solicitação foram removidos. O valor reembolsado agora é calculado automaticamente.

  • O CustomBatch foi removido.

  • O Refund foi removido. Use refundOrder ou refundItem.

  • O campo paymentMethod foi removido.

  • Os métodos v2orders.returnlineitem e orders.refund foram substituídos por orderreturns.creatOrderReturn e orderreturns.process.

  • Os campos customer.email, channelType e lineItem.product.channel foram removidos.

  • O campo promotions foi removido do serviço TestOrder e o formato dele foi alterado em Order.

7. Atualizar chamadas para o serviço orderinvoice

  • Os campos amountPretax e amountTax foram substituídos por priceAmount e taxAmount, respectivamente. O campo priceAmount pode ser antes ou depois dos tributos, dependendo da localização do pedido.

  • Saldos removidos (comerciante, cliente, Google) em invoiceSummary e campos relacionados à cobrança de promoção.

8. Remover funcionalidades não incluídas na v2.1

Vários outros recursos foram removidos da API Content na v2.1. Revise a lista a seguir e atualize sua inscrição conforme necessário:

  • O XML não é mais compatível. Para mais informações sobre a mudança para JSON, consulte Descontinuação do suporte a XML na API Content for Shopping.

  • O parâmetro dryRun foi removido. Essa mudança se aplica a todas as chamadas de API.

  • Todos os métodos HTTP BATCH foram removidos. Use customBatch.

  • O método patch foi removido dos seguintes serviços:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • O serviço orderpayments foi removido.

Testar a migração

Para mais informações sobre como testar as mudanças nos aplicativos após a migração para a v2.1, consulte Testar usos da API Content for Shopping. Se você tiver problemas ao testar as atualizações, entre em contato com nossa equipe.

Outras mudanças na v2.1

Além das mudanças que exigem atualizações, a v2.1 também apresenta vários novos recursos e mudanças não destrutivas:

  • Novos serviços:

    • O novo serviço localinventory permite fazer atualizações de produtos locais (em vez do serviço inventory na v2).

    • O novo serviço orderreturns facilita o gerenciamento do Comprar com o Google (antes conhecido como Ações do Shopping), permitindo que você processe devoluções sem precisar usar o serviço orders.

  • Com os feeds complementares, é possível fazer atualizações parciais de produtos.

  • Outras mudanças no serviço products:

    • As solicitações do products.insert não informam mais avisos ou erros não fatais. Assim, você pode inserir produtos e fazer atualizações subsequentes para resolver problemas usando regras de feed no Merchant Center, como faria com feeds gerenciados fora da API Content.

    • O products.update foi adicionado para permitir que você faça atualizações em um conjunto escolhido de campos de produtos. Para mais informações sobre possíveis usos, consulte o guia.

    • Valores inválidos para os seguintes atributos não acionam mais erros de inserção e são retornados como parte de itemLevelIssues pelo serviço productstatus:

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

    • Agora, os atributos personalizados são recursivos, o que elimina a necessidade de grupos personalizados.

    • Os atributos personalizados agora têm um campo groupValues além do campo value original. Exatamente um dos campos precisa ser definido.