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 descontinuada. Migre para a v2.1 imediatamente.

Migrar seu aplicativo

Migrar da v2 para a v2.1 envolve a atualização dos URLs do endpoint para chamar as novas versões da v2.1 e a modificação dos aplicativos para considerar as alterações interruptivas introduzidas na v2.1.

Atualizar suas 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, 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 ver informações completas sobre os serviços e endpoints v2.1, consulte a Referência da API.

Faça as alterações necessárias

Além de atualizar os URLs para suas chamadas de API, você também precisa atualizar seu aplicativo para considerar várias alterações interruptivas introduzidas na v2.1. Leia as seções a seguir e atualize sua inscrição, conforme necessário.

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

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

  • Use novos feeds suplementares ou products.update para atualizações parciais do produto. É possível fazer atualizações em todos os campos de produtos mutáveis, incluindo aqueles que foram atualizados anteriormente com inventory.set (exceto aqueles exclusivos para localinventory). Consulte Migrar para feeds suplementares 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 inactive do link 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 são 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 Google 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 o 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 corta os espaços em branco à esquerda e à direita no offerId e mescla vários caracteres de espaço em branco em um. Essa mudança não afeta os valores de offerId que estão em conformidade com a sintaxe offerId recomendada.

  • Agora os preços são validados antes da inserção do produto. Apenas os seguintes caracteres são permitidos na string de valor: +, -, . e dígitos (ou seja, 0-9). 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 ProductId para conferir as informações completas do produto.

4. Atualizar chamadas para o serviço productstatuses

  • O atributo product e o parâmetro includeAttributes foram removidos. Para recuperar os 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, independente de o produto ser válido ou não.

  • 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 Imparcialidade (MFA) do Marketplace ou semelhante, as chamadas que incluírem dados fiscais falharão. Se o pedido for realizado em um estado que não seja MFA, o tributo será calculado com base nas configurações definidas no Merchant Center. Se não for configurado, o tributo calculado vai ser 0.

  • Os campos InStoreRefundLineItem e ReturnRefundLineItem amountPretax e amountTax foram substituídos por priceAmount e taxAmount, respectivamente. O priceAmount pode ser com ou sem tributos, dependendo da localização 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.

  • O CustomBatch foi removido.

  • O 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 sem tributos ou sem tributos, dependendo do local do pedido.

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

8. Remover a funcionalidade não incluída na v2.1

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

  • O suporte a XML não é mais oferecido. 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 alterações nos aplicativos após a migração para a v2.1, consulte Como testar usos da API Content for Shopping. Se você encontrar problemas ao testar as atualizações, poste seu problema no fórum da API Content.

Outras mudanças na v2.1

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

  • Novos serviços:

    • O novo serviço localinventory permite fazer atualizações de produtos disponíveis na loja física (no lugar do serviço inventory na v2).

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

  • Os feeds complementares permitem fazer atualizações parciais do produto.

  • Outras mudanças no serviço products:

    • As solicitações products.insert não informam mais avisos ou erros não fatais. Assim, é possível inserir produtos e fazer atualizações 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 possíveis usos, consulte o guia.

    • Valores inválidos para os atributos abaixo 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
    • 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 deve ser definido.