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, mediante segmentaciones geográficas predefinidas. En esta guía, se proporcionan ejemplos de cómo definir cada tipo de región y 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 segmentaciones geográficas, no ambos.

Elegibilidad de las regiones

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

regionalInventoryEligible

A fin de ser apta para usarse con el servicio regionalinventory, una región debe cumplir con los siguientes criterios:

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

shippingEligible

A fin de ser apta para usarse con el servicio shippingsettings, una región debe cumplir con los siguientes criterios:

• La región se debe definir con códigos postales.
• La región debe ser parte de un país que admita el servicio shippingsettings.

Ejemplos

Aquí hay 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();
  }
}

Cómo crear una región con códigos postales

Puedes utilizar el método regions.create para crear una región definida como un grupo 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 el 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 regiones.

Existe 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 de forma interna de una MCA a todas sus cuentas secundarias, por lo que, en las MCA más grandes, es posible que alcances tu límite de almacenamiento con rapidez. En este caso, una solución alternativa es administrar regions y shippingsettings a nivel del ID del comercio. No es posible aumentar la cuota de tus regiones más allá del límite de 2 MB.

Cómo crear una región con segmentaciones geográficas

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 segmentaciones geográficas, que son áreas geográficas predefinidas. Algunos ejemplos de tipos de segmentación geográfica incluyen países, estados, ciudades, vecindarios y aeropuertos. Sin embargo, actualmente 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 ID de geosegmentaciones, incluidas las que se pueden usar con el servicio regions, consulta Geotargets. En el siguiente ejemplo, se crea una región nueva cuando se proporcionan los IDs de geosegmentación de tres estados brasileños.

Para crear la región, realiza una solicitud POST con la siguiente URL y el 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 una regionId y dos campos de estado de elegibilidad. Si el valor de 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 precio regional mediante la región basada en código postal creada en el ejemplo anterior, que tiene un regionId de “456789”.

Para crear la anulación, realiza una solicitud POST con la siguiente URL y el 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”
}