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 segmentaciones geográficas predefinidas. 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 hacer lo siguiente con los métodos asociados:
- Crear varias regiones en una sola solicitud:
regions:batchCreate - Borrar varias regiones a la vez:
regions:batchDelete - Actualizar 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.
Cómo crear 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
Crea 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 exitosa 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
}
]
}
Cómo actualizar varias regiones
En este ejemplo, se muestra cómo usar BatchUpdateRegions para actualizar el displayName y el postalCodeArea de dos regiones existentes. Debes proporcionar un region.name para actualizar la región segmentada.
Solicitud
Crea 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 exitosa 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 exitosa 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 dentro del lote (por ejemplo, si no se puede crear una región), fallará todo el lotey no se realizarán cambios. La API mostrará 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 de región.
- Cuotas: Estos extremos usan los mismos grupos de cuotas que sus
contrapartes de operación única (
regions.create,regions.delete,regions.update).
Errores y problemas habituales
Estos son algunos errores comunes y sus soluciones.
"The number of requests in a batch is too large"
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 ocurre cuando falta un campo obligatorio. El mensaje de error especifica el parámetro faltante.
Los mensajes de error son los siguientes:
- Para
batchCreate:[regionId] Required parameter: regionId - Para
batchUpdate:[region.name] Required field not provided. - Para
batchDelete:[name] Required parameter: name
Para solucionar este problema, verifica que todos los campos obligatorios estén presentes en cada operación. Por ejemplo, cada entrada en una solicitud batchUpdate debe incluir el region.name.
Si publicas la siguiente solicitud, se producirá un error:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Region with specified ID already exists"
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 solucionar este problema, verifica que todos los valores de regionId sean únicos dentro del lote y no entren en conflicto con las regiones existentes.
"Duplicate value found for field region.name or regionId found"
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 dentro de una sola solicitud por lotes.
"Item not found"
Cuando se usa batchUpdate, si no existe alguna región especificada en la solicitud, fallará todo el lote con un error 404 NOT_FOUND. Esto es diferente de batchDelete, que se realiza correctamente para las regiones inexistentes.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Para solucionar este problema, verifica que existan todas las regiones que intentas actualizar antes de enviar la solicitud.