Una región de la API de Merchant representa una región geográfica que puedes usar como objetivo relacionado con el recurso accounts.products.regionalInventories. Puedes definir regiones como colecciones de códigos postales o, en algunos países, con la segmentación geográfica predefinida. Para obtener más información, consulta Cómo configurar regiones.
La API de Merchant proporciona extremos por lotes para administrar tus regiones, lo que te permite crear, actualizar y borrar hasta 100 regiones en una sola llamada a la API. Esto es ideal para los comercios que administran la disponibilidad y los precios regionales (RAAP) a gran escala, ya que mejora la eficiencia y simplifica la integración.
Descripción general
La API de Batch te permite lograr lo siguiente con los métodos asociados:
- Crea varias regiones en una sola solicitud:
regions:batchCreate - Borra varias regiones a la vez:
regions:batchDelete - Actualiza varias regiones de forma simultánea:
regions:batchUpdate
Requisitos previos
Todas las solicitudes por lotes requieren el rol de usuario ADMIN para la autenticación.
Crea varias regiones
En este ejemplo, se muestra cómo crear dos regiones nuevas (una definida por códigos postales y otra por segmentación geográfica) en una sola llamada de BatchCreateRegions.
Solicitud
Construye la URL de la solicitud de la siguiente manera:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
El cuerpo de la solicitud contiene una lista de requests, en la que cada objeto especifica un regionId y los datos de region que se crearán.
{
"requests": [
{
"regionId": "seattle-area-98340",
"region": {
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
}
}
},
{
"regionId": "co-de-states",
"region": {
"displayName": "Colorado and Delaware",
"geoTargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
}
}
}
]
}
Respuesta
Una solicitud correcta devuelve una lista de los nuevos objetos region.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
"displayName": "Colorado and Delaware",
"geotargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
},
"regionalInventoryEligible": false,
"shippingEligible": false
}
]
}
Actualiza varias regiones
En este ejemplo, se muestra cómo usar BatchUpdateRegions para actualizar displayName y postalCodeArea para dos regiones existentes. Debes proporcionar un region.name para actualizar la región objetivo.
Solicitud
Construye la URL de la solicitud de la siguiente manera:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
El cuerpo de la solicitud contiene una lista de requests. Cada objeto debe especificar los datos de region que se actualizarán. El campo region.name debe contener el ID de la región que se actualizará, por ejemplo,"98005". Especifica el recurso como name en lugar de accounts/{ACCOUNT_ID}/regions/name. Incluir updateMask para indicar los campos que se cambiarán es opcional.
{
"requests": [
{
"region": {
"name": "98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
},
{
"region": {
"name": "07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
}
]
}
Respuesta
Una solicitud correcta devuelve una lista de los objetos region actualizados.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
}
]
}
Cómo borrar varias regiones
Puedes borrar varias regiones en una sola llamada.
Solicitud
En este ejemplo, se muestra cómo usar BatchDeleteRegions para borrar dos regiones en una sola llamada.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
El cuerpo de la solicitud contiene una lista de requests, en la que cada objeto especifica el name (sin "accounts/{ACCOUNT_ID}/regions/") de la región que se borrará.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Respuesta
Una solicitud correcta devuelve un cuerpo de respuesta vacío, lo que indica que se borraron las regiones especificadas (o que no existían).
{}
Limitaciones
Antes de comenzar, ten en cuenta estas reglas:
- Operaciones atómicas: Las solicitudes por lotes son atómicas. Si falla alguna operación individual dentro del lote (por ejemplo, si no se puede crear una región), fallará todo el lote y no se realizará ningún cambio. La API devolverá un error que detalla la causa de la falla.
- Límites de lotes: Cada solicitud por lotes puede contener un máximo de 100 operaciones regionales.
- Cuotas: Estos extremos usan los mismos grupos de cuotas que sus contrapartes de una sola operación (
regions.create,regions.delete,regions.update).
Errores y problemas habituales
A continuación, se indican algunos errores comunes y sus soluciones.
"La cantidad de solicitudes en un lote es demasiado grande"
Este error se produce si la cantidad de operaciones en el array de solicitudes supera el límite de 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Para solucionar este problema, divide tus operaciones en varias solicitudes por lotes de 100 o menos.
Falta un campo obligatorio
Este error se produce cuando falta un campo obligatorio. El mensaje de error especifica el parámetro faltante.
Estos son los mensajes de error:
- Para
batchCreate:[regionId] Required parameter: regionId - Para
batchUpdate:[region.name] Required field not provided. - Para
batchDelete:[name] Required parameter: name
Para corregir este problema, verifica que todos los campos obligatorios estén presentes en cada operación. Por ejemplo, cada entrada en una solicitud de batchUpdate debe incluir el region.name.
Publicar la siguiente solicitud genera un error:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Ya existe una región con el ID especificado"
Se produce un error si intentas crear una región con un regionId que ya existe.
El mensaje de error es [regionId] Region with specified id already exists..
Para corregir este problema, verifica que todos los valores de regionId sean únicos dentro del lote y no entren en conflicto con las regiones existentes.
"Se encontró un valor duplicado para el campo region.name o regionId"
Se produce un error si intentas crear o actualizar varias regiones con el mismo ID en una sola solicitud por lotes.
El mensaje de error es Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Para solucionar este problema, verifica que todos los valores de regionId (para batchCreate) o region.name (para batchUpdate) sean únicos en una sola solicitud por lotes.
“No se encontró el elemento”
Cuando se usa batchUpdate, si no existe alguna de las regiones especificadas en la solicitud, todo el lote fallará con un error 404 NOT_FOUND. Esto es diferente de batchDelete, que se ejecuta correctamente para las regiones inexistentes.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Para solucionar este problema, verifica que todas las regiones que intentas actualizar existan antes de enviar la solicitud.