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 segmentos geográficos predefinidos. En esta guía, se proporcionan ejemplos de cómo definir cada tipo de región, así como de cómo crear una anulación regional de precios. Para obtener más información sobre el servicio regions, incluidos todos los métodos y parámetros disponibles, consulta la documentación de referencia.

Elegibilidad por región

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 devuelve 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 el servicio de 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 mínimos de tamaño para el área geográfica y la población en línea.

shippingEligible

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

  • La región se debe definir con códigos postales.
  • La región debe formar parte de un país admitido por el servicio de shippingsettings.

Ejemplos

Aquí tienes 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 método regions.create 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 (EE.UU.) especificando 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*"
      }
    ]
   }
}

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

Crea una región con la segmentación geográfica

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. Entre los ejemplos de tipos de segmentación geográfica, se 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 con todos los IDs de segmentación geográfica, incluidas las segmentaciones geográficas que se pueden usar con el servicio de regions, consulta Segmentaciones geográficas. En el siguiente ejemplo, se crea una región nueva proporcionando los IDs de segmentación geográfica 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 devuelve un objeto de respuesta que incluye un 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 con la región basada en el código postal 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 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”
}