Migrar da API Content v2 para a v2.1

Em março de 2019, nós lançamos a versão 2.1 da API Content for Shopping e, em abril de 2021, nós 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 v2.1 e a modificação dos aplicativos para considerar as mudanças interruptivas 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 v2.1.

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

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 os serviços e endpoints da v2.1, consulte a Referência da API.

Fazer as alterações necessárias

Além de atualizar os URLs das chamadas de API, você também precisa atualizar seu aplicativo para considerar várias mudanças interruptivas introduzidas na v2.1. Analise as seções a seguir e atualize seu aplicativo conforme necessário.

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

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

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

  • Use o novo localinventory serviço para atualizações de produtos locais.

2. Atualizar chamadas para o serviço accounts

  • As chamadas para o método accounts.update na v2.1 substituem completamente o accounts recurso, em vez de apenas atualizar os campos incluídos na solicitação. Para evitar a exclusão de campos no recurso accounts, atualize as 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 usando 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 corta espaços em branco à esquerda e à direita no 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 em conformidade com a sintaxe recomendada offerId.

  • Os preços agora 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 includeAttributes da v2 foi descontinuada. Em vez disso, use products.get com o ProductId para conferir 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 atributos do produto correspondente 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, independentemente 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 fiscais, porque eles são calculados automaticamente. Se o pedido for atendido em um estado com uma Lei de Justiça de Mercado (MFA, na sigla em inglês) ou semelhante, as chamadas que incluem dados fiscais falharão. Se o pedido for atendido em um estado sem MFA, o imposto será calculado com base nas configurações definidas no Merchant Center. Se não estiver configurado, o imposto calculado será 0.

  • Os campos InStoreRefundLineItem e ReturnRefundLineItem amountPretax e amountTax foram substituídos por priceAmount e taxAmount, respectivamente. priceAmount pode ser antes ou depois dos impostos, dependendo do local do pedido.

  • Os campos ShipLineItem carrier, shipmentId e trackingId 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.

  • CustomBatch foi removido.

  • Refund foi removido. Use refundOrder ou refundItem.

  • O campo paymentMethod foi removido.

  • Os métodos orders.returnlineitem e orders.refund da v2 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 impostos, dependendo do local do pedido.

  • Os saldos (comerciante, cliente, Google) foram removidos em invoiceSummary e campos relacionados à cobrança de promoções.

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

Vários outros recursos foram removidos da API Content na v2.1. Analise a lista a seguir e atualize seu aplicativo conforme necessário:

  • O XML não é mais aceito. Para mais informações sobre como mudar para JSON, consulte Desativaçã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ê encontrar problemas ao testar as atualizações, você pode entrar em contato conosco.

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 interruptivas:

  • Novos serviços:

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

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

  • Os feeds complementares permitem fazer atualizações parciais de produtos.

  • Outras mudanças no serviço products:

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

    • 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 o uso possível, 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 productstatus serviço:

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

    • Os atributos personalizados agora 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.