Regiones

El servicio regions te permite crear y administrar regiones geográficas que puedes usar como objetivos con los servicios regionalinventory y shippingsettings. Puedes definir regiones como colecciones de códigos postales o, en algunos países, con objetivos geográficos predefinidos . En esta guía, se proporcionan ejemplos de cómo definir cada tipo de región, así como también cómo crear una anulación de precios regional. Para obtener información adicional sobre el servicio regions, incluidos todos los métodos y parámetros disponibles, consulta la documentación de referencia.

Nota: Cada definición de región solo puede contener códigos postales o bien objetivos geográficos, pero no ambos.

Elegibilidad de la región

Cuando creas una región, el servicio de regiones determina si puedes usarla con otros servicios de la API de Content. El objeto de respuesta que se muestra para una llamada regions.create exitosa incluye dos campos booleanos, regionalInventoryEligible y shippingEligible, que indican si puedes usar la región con los servicios regionalinventory y shippingsettings, respectivamente.

regionalInventoryEligible

Para poder usar una región con el servicio regionalinventory, esta debe cumplir con los siguientes criterios:

• El regionId, que especificas cuando creas una región, solo debe contener dígitos y, al menos, 2.
• La región debe cumplir con los requisitos mínimos de tamaño para el área geográfica y la población en línea.

shippingEligible

Para poder usar una región con el servicio shippingsettings, esta debe cumplir con los siguientes criterios:

• La región debe definirse con códigos postales.
• La región debe formar parte de un país compatible con el servicio shippingsettings.

Ejemplos

Esta es una muestra de código completa que puedes usar para crear una región nueva en 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();
  }
}

Crea una región con códigos postales

Puedes usar el regions.create método para crear una región definida como una colección de códigos postales. En el siguiente ejemplo, se crea una región nueva para el estado de Arizona en EE.UU. mediante la especificación de un rango de códigos postales.

Para crear la región, realiza una solicitud POST con la siguiente URL y cuerpo de la solicitud:

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

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

Nota: Si recibes el error "quota/too_many_regions", significa que te quedaste sin almacenamiento en tu cuenta para las regiones.

Hay un límite estricto de 2 MB de datos para regions y shippingsettings por cuenta de Merchant Center. La configuración de envío y región se copia internamente de una cuenta de MCA a todas sus subcuentas, por lo que, en el caso de las cuentas de MCA más grandes, es posible que alcances el límite de almacenamiento rápidamente. En este caso, una solución alternativa es administrar regions y shippingsettings a nivel del ID de comercio. No hay forma de aumentar la cuota de regiones más allá del límite de 2 MB.

Crea una región con objetivos geográficos

En el caso de las regiones de Brasil y Rusia, también puedes usar el método regions.create para crear una región definida como una colección de objetivos geográficos, que son áreas geográficas predefinidas. Entre los ejemplos de tipos de objetivos geográficos, se incluyen países, estados, ciudades, vecindarios y aeropuertos. Sin embargo, el servicio regions solo admite el tipo "Estado" para Brasil y el tipo "Región" para Rusia. Para descargar un archivo CSV de todos los IDs de objetivos geográficos, incluidos los que se pueden usar con el regions servicio, consulta Objetivos geográficos. En el siguiente ejemplo, se crea una región nueva proporcionando los IDs de objetivos geográficos de tres estados brasileños.

Para crear la región, realiza una solicitud POST con la siguiente URL y cuerpo de la solicitud:

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

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

Usa regiones para crear anulaciones de precios regionales

Cuando creas una región, el servicio regions muestra un objeto de respuesta que incluye un regionId y dos campos de estado de elegibilidad. Si el valor regionalInventoryEligible es true, puedes usar el servicio regionaliventory para crear una anulación que establezca un precio diferente para la región. En el siguiente ejemplo, se crea una anulación de precios regional con la región basada en códigos postales que se creó en el ejemplo anterior, que tiene un regionId de "456789".

Para crear la anulación, realiza una solicitud POST con la siguiente URL y cuerpo de la solicitud:

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

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