Regiões

Gostaríamos de apresentar a versão Beta da API Merchant. Esta é a nova versão da API Content for Shopping e o futuro.

Para mais informações sobre como a API Merchant pode melhorar sua integração e como você pode ajudar a definir o futuro, consulte Anúncio da API Merchant Beta.

O serviço regions permite criar e gerenciar regiões geográficas que podem ser usadas como destinos com os serviços regionalinventory e shippingsettings. É possível definir regiões como coleções de códigos postais ou, em alguns países, usando segmentações geográficas predefinidas. Neste guia, fornecemos exemplos de como definir cada tipo de região e como criar uma modificação de preços regional. Para mais informações sobre o serviço regions, incluindo todos os métodos e parâmetros disponíveis, consulte a documentação de referência.

Observação :cada definição de região pode conter apenas códigos postais ou segmentações geográficas, mas não ambos.

Qualificação por região

Quando você cria uma região, o serviço de regiões determina se é possível usá-la com outros serviços da API Content. O objeto de resposta retornado para uma chamada regions.create bem-sucedida inclui dois campos booleanos, regionalInventoryEligible e shippingEligible, que indicam se é possível usar a região com os serviços regionalinventory e shippingsettings, respectivamente.

regionalInventoryEligible

Para se qualificar para uso com o serviço regionalinventory, uma região precisa atender aos seguintes critérios:

• O regionId, que você especifica ao criar uma região, precisa conter apenas dígitos e pelo menos seis dígitos.
• A região precisa atender aos requisitos mínimos de tamanho para a área geográfica e a população on-line.

shippingEligible

Para se qualificar para uso com o serviço shippingsettings, uma região precisa atender aos seguintes critérios:

• A região precisa ser definida usando CEPs/códigos postais.
• A região precisa fazer parte de um país compatível com o serviço shippingsettings.

Exemplos

Este é um exemplo de código completo que pode ser usado para criar uma nova região em Java:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package shopping.content.v2_1.samples.regions;

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.services.content.model.Region;
import com.google.api.services.content.model.RegionPostalCodeArea;
import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import shopping.content.v2_1.samples.ContentSample;

/**
 * Creates a region. The region created here can be used with the regional inventory service.
 * Regional availability and pricing lets you provide product availability and variable pricing
 * based on your business presence and the location of your customer base. Regional availability and
 * pricing is available for products advertised through Shopping ads on Google Search, and listed in
 * free listings on the Shopping tab.
 */
public class RegionCreateSample extends ContentSample {
  public RegionCreateSample(String[] args) throws IOException {
    super(args);
  }

  @Override
  public void execute() throws IOException {
    checkNonMCA();

    // Creates a List of Postal Code Area Postal Code Ranges.
    // This allows you to flexibly define regions as combinations of postal code
    // ranges. Each postal code range in the list has its own start and end zip code.
    List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges =
        new ArrayList<RegionPostalCodeAreaPostalCodeRange>();

    // Creates a new postal code range from two postal code values.
    // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)
    RegionPostalCodeAreaPostalCodeRange postalCodeRange =
        new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925");

    // Adds the NY State postal code range into the list of postal code ranges that a postal
    // code area accepts.
    postalCodeRanges.add(postalCodeRange);

    // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code
    // ranges, and the US CLDR territory/country code that the postal code ranges applies to.
    RegionPostalCodeArea postalCodeArea =
        new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US");

    // Creates a region with example values for displayName and postalCodeArea
    Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea);

    // Tries to create the region, and catches any exceptions
    try {
      System.out.println("Creating region");
      Region result =
          content
              .regions()
              .create(this.config.getMerchantId().longValue(), region)
              .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits
              .execute();
      System.out.println("Listing succesfully created region");
      System.out.println(result);
    } catch (GoogleJsonResponseException e) {
      checkGoogleJsonResponseException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    new RegionCreateSample(args).execute();
  }
}

Criar uma região usando códigos postais

É possível usar o método regions.create para criar uma região definida como uma coleção de códigos postais. O exemplo abaixo cria uma nova região para o estado do Arizona, EUA, especificando um intervalo de códigos postais.

Para criar a região, faça uma solicitação POST com o seguinte URL e corpo:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

Observação: se você receber o erro "quota/too_muitos_regiões", significa que você ficou sem espaço de armazenamento na sua conta para regiões.

Há um limite rígido de 2 MB de dados para regions e shippingsettings por conta do Merchant Center. As configurações de frete e região são copiadas internamente de uma MCA para todas as subcontas. Portanto, em MCAs maiores, talvez você atinja rapidamente o limite de armazenamento. Nesse caso, uma solução alternativa é gerenciar regions e shippingsettings no nível do ID do comerciante. Não é possível aumentar a cota das regiões além do limite de 2 MB.

Criar uma região usando segmentações geográficas

Para regiões do Brasil e da Rússia, também é possível usar o método regions.create para criar uma região definida como uma coleção de segmentações geográficas, que são áreas geográficas predefinidas. Exemplos de tipos de segmentação geográfica incluem países, estados, cidades, bairros e aeroportos. No entanto, o serviço regions atualmente oferece suporte apenas ao tipo "Estado" para o Brasil e o tipo "Região" para a Rússia. Para fazer o download de um arquivo csv de todos os IDs de segmentação geográfica, incluindo as segmentações geográficas que podem ser usadas com o serviço regions, consulte Segmentações geográficas. O exemplo abaixo cria uma nova região fornecendo os IDs de segmentação geográfica de três estados brasileiros.

Para criar a região, faça uma solicitação POST usando o seguinte URL e o seguinte corpo:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

Usar regiões para criar substituições de preço regionais

Quando você cria uma região, o serviço regions retorna um objeto de resposta que inclui um regionId e dois campos de status de qualificação. Se o valor regionalInventoryEligible for true, será possível usar o serviço regionaliventory para criar uma substituição que defina um preço diferente para a região. O exemplo abaixo cria uma substituição de preço regional usando a região baseada em código postal criada no exemplo acima, que tem um regionId de "456789".

Para criar a substituição, faça uma solicitação POST usando o seguinte URL e o corpo da solicitação:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory

{
  “regionId”: "456789"
  “price”: {
    value: “10”
    currency: “USD”
  },
  “availability”: “in stock”
}