Regiones

Nos gustaría presentar la versión beta de la API de Merchant. Es la nueva versión del Content API for Shopping y el futuro.

Para obtener información sobre cómo la API de Merchant Center puede mejorar tu integración y cómo puedes ayudar a definir la en el futuro, consulta Cómo anunciar la versión beta de la API de Merchant Center.

El servicio regions te permite crear y administrar regiones geográficas que que puedes usar como objetivos regionalinventory y shippingsettings de Google Cloud. Puede definir las regiones como colecciones de códigos postales o, en en algunos países, mediante el uso geotargets. En esta guía, se proporciona ejemplos de cómo definir cada tipo de región y de cómo crear una anulación de precio. 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.

Nota: La definición de cada región solo puede contener códigos postales o pero no ambas.

Elegibilidad de la región

Cuando creas una región, el servicio de regiones determina si puedes usar región con otros servicios de Content API. El objeto de respuesta que se muestra para un 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 usarla con el servicio de regionalinventory, una región debe cumplir los siguientes criterios:

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

shippingEligible

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

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

Ejemplos

Este es un ejemplo de código completo que puedes usar para crear una nueva región 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 la regions.create para crear una región definida como un conjunto de códigos postales. El ejemplo a continuación crea una nueva región para el estado estadounidense de Arizona especificando un rango de códigos postales.

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

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. Configuración de envío y región se copian internamente de una MCA a todas sus cuentas secundarias, por lo que en el caso de Con las MCA, puedes alcanzar rápidamente tu límite de almacenamiento. En este caso, una solución alternativa es para administrar regions y shippingsettings al nivel del ID del comerciante. No hay para aumentar la cuota de tu región más allá del límite de 2 MB.

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

Para las regiones de Brasil y Rusia, también puedes usar el método regions.create. para crear una región definida como un conjunto de orientaciones geográficas, que están predefinidas en ciertas áreas geográficas. Algunos ejemplos de tipos de orientaciones geográficas son países, estados, ciudades, vecindarios y aeropuertos. Sin embargo, en la actualidad, el servicio regions solo admite el tipo “Estado” para Brasil y el tipo “Región” para Rusia. Para descargue un archivo csv de todos los ID de las orientaciones geográficas, incluidas las orientaciones geográficas que se pueden que se usa con el servicio regions, consulta Segmentaciones geográficas En el siguiente ejemplo, se crea una nueva región, ya que proporciona 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 solicitud cuerpo:

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 botón El valor de regionalInventoryEligible es true; puedes usar el regionaliventory servicio para crear una anulación que establezca un precio diferente para la región. El ejemplo a continuación crea una anulación del precio regional con el código postal basado región 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 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”
}