Регион API продавца представляет собой географический регион, который можно использовать в качестве целевого объекта для ресурса accounts.products.regionalInventories . Регионы можно определить как наборы почтовых индексов или, в некоторых странах, с помощью предопределенных геотаргетов. Подробнее см. в разделе «Настройка регионов» .
API для продавцов предоставляет пакетные конечные точки для управления регионами, позволяя создавать, обновлять и удалять до 100 регионов за один вызов API. Это идеальное решение для продавцов, которым необходимо масштабное управление региональной доступностью и ценообразованием (RAAP), повышая эффективность и упрощая интеграцию.
Обзор
Пакетный API позволяет выполнять следующие действия с помощью соответствующих методов:
- Создание нескольких регионов в одном запросе:
regions:batchCreate - Удалить несколько регионов одновременно:
regions:batchDelete - Обновить несколько регионов одновременно:
regions:batchUpdate
Предпосылки
Для аутентификации всех пакетных запросов требуется роль пользователя ADMIN .
Создать несколько регионов
В этом примере показано, как создать два новых региона — один, определенный почтовыми индексами, а другой — геотаргетингом — за один вызов BatchCreateRegions .
Запрос
Создайте URL-адрес запроса следующим образом:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Тело запроса содержит список requests , где каждый объект указывает regionId и данные region , которые нужно создать.
{
"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"
]
}
}
}
]
}
Ответ
Успешный запрос возвращает список новых объектов 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
}
]
}
Обновить несколько регионов
В этом примере показано, как использовать BatchUpdateRegions для обновления displayName и postalCodeArea для двух существующих регионов. Для обновления целевого региона необходимо указать region.name .
Запрос
Создайте URL-адрес запроса следующим образом:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Тело запроса содержит список requests . Каждый объект должен указывать данные о region для обновления. Поле region.name должно содержать идентификатор обновляемого региона, например, «98005». Ресурс указывается в формате name , а не accounts/{ACCOUNT_ID}/regions/name . Добавление updateMask для указания полей, которые нужно изменить, необязательно.
{
"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"
}
]
}
Ответ
Успешный запрос возвращает список обновленных объектов region .
{
"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
}
]
}
Удалить несколько регионов
Вы можете удалить несколько регионов за один вызов.
Запрос
В этом примере показано, как использовать BatchDeleteRegions для удаления двух регионов за один вызов.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Тело запроса содержит список requests , где каждый объект указывает name (без "accounts/{ACCOUNT_ID}/regions/" ) региона, который нужно удалить.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Ответ
Успешный запрос возвращает пустое тело ответа, указывающее, что указанные регионы были удалены (или не существовали).
{}
Ограничения
Прежде чем начать, помните следующие правила:
- Атомарные операции : пакетные запросы являются атомарными. Если какая-либо отдельная операция в пакете завершится неудачей (например, не удастся создать один регион), весь пакет завершится неудачей , и изменения не будут внесены. API вернёт ошибку с подробным описанием причины сбоя.
- Ограничения пакета : каждый пакетный запрос может содержать максимум 100 региональных операций.
- Квоты : эти конечные точки используют те же группы квот, что и их аналоги с одной операцией (
regions.create,regions.delete,regions.update).
Распространенные ошибки и проблемы
Вот несколько распространенных ошибок и их решений.
«Количество запросов в пакете слишком велико»
Эта ошибка возникает, если количество операций в массиве запросов превышает лимит в 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Чтобы исправить это, разделите ваши операции на несколько пакетных запросов по 100 или менее.
Обязательное поле отсутствует
Эта ошибка возникает, когда отсутствует обязательное поле. В сообщении об ошибке указан отсутствующий параметр.
Сообщения об ошибках следующие:
- Для
batchCreate:[regionId] Required parameter: regionId - Для
batchUpdate:[region.name] Required field not provided. - Для
batchDelete:[name] Required parameter: name
Чтобы исправить это, проверьте наличие всех обязательных полей в каждой операции. Например, каждая запись в запросе batchUpdate должна включать region.name . Отправка следующего запроса приводит к ошибке:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
«Регион с указанным ID уже существует»
При попытке создать регион с уже существующим regionId возникнет ошибка.
Сообщение об ошибке: [regionId] Region with specified id already exists.
Чтобы исправить это, убедитесь, что все значения regionId уникальны в пределах пакета и не конфликтуют с существующими регионами.
«Обнаружено повторяющееся значение для поля region.name или regionId»
Ошибка возникает при попытке создать или обновить несколько регионов с одинаковым идентификатором в одном пакетном запросе.
Сообщение об ошибке: Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}. .
Чтобы исправить это, убедитесь, что все значения regionId (для batchCreate ) или region.name (для batchUpdate ) уникальны в пределах одного пакетного запроса.
«Товар не найден»
При использовании batchUpdate , если какой-либо регион, указанный в запросе, не существует, весь пакет завершится ошибкой 404 NOT_FOUND . Это отличается от batchDelete , который успешно завершается для несуществующих регионов.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Чтобы исправить это, перед отправкой запроса убедитесь, что все регионы, которые вы пытаетесь обновить, существуют.