Uma região da API Merchant representa uma região geográfica que pode ser usada como um
destino relacionado ao recurso accounts.products.regionalInventories. É possível definir regiões como coleções de CEPs ou, em alguns países, usando segmentações geográficas predefinidas. Para mais informações, consulte Configurar
regiões.
A API Merchant fornece endpoints em lote para gerenciar suas regiões, permitindo que você crie, atualize e exclua até 100 regiões em uma única chamada de API. Isso é ideal para comerciantes que gerenciam disponibilidade e preços regionais (RAAP) em grande escala, melhorando a eficiência e simplificando a integração.
Visão geral
A API Batch permite realizar o seguinte com os métodos associados:
- Criar várias regiões em uma única solicitação:
regions:batchCreate - Excluir várias regiões de uma só vez:
regions:batchDelete - Atualizar várias regiões simultaneamente:
regions:batchUpdate
Pré-requisitos
Todas as solicitações em lote exigem a função de usuário ADMIN para autenticação.
Criar várias regiões
Este exemplo mostra como criar duas novas regiões (uma definida por códigos postais e outra por segmentação geográfica) em uma única chamada de BatchCreateRegions.
Solicitação
Crie o URL da solicitação da seguinte maneira:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
O corpo da solicitação contém uma lista de requests, em que cada objeto especifica um regionId e os dados region a serem criados.
{
"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"
]
}
}
}
]
}
Resposta
Uma solicitação bem-sucedida retorna uma lista dos novos 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
}
]
}
Atualizar várias regiões
Este exemplo mostra como usar BatchUpdateRegions para atualizar displayName
e postalCodeArea de duas regiões. Você precisa fornecer um region.name para atualizar a região segmentada.
Solicitação
Crie o URL da solicitação da seguinte maneira:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
O corpo da solicitação contém uma lista de requests. Cada objeto precisa especificar os dados region a serem atualizados. O campo region.name precisa conter o ID da região a ser atualizada, por exemplo,"98005". Especifique o recurso como name em vez de accounts/{ACCOUNT_ID}/regions/name. Incluir updateMask para indicar os campos a serem mudados é 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"
}
]
}
Resposta
Uma solicitação bem-sucedida retorna uma lista dos objetos region atualizados.
{
"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
}
]
}
Excluir várias regiões
É possível excluir várias regiões em uma única chamada.
Solicitação
Este exemplo mostra como usar BatchDeleteRegions para excluir duas regiões em uma
única chamada.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
O corpo da solicitação contém uma lista de requests, em que cada objeto especifica o
name (sem "accounts/{ACCOUNT_ID}/regions/") da região a ser excluída.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Resposta
Uma solicitação bem-sucedida retorna um corpo de resposta vazio, indicando que as regiões especificadas foram excluídas (ou não existiam).
{}
Limitações
Antes de começar, considere estas regras:
- Operações atômicas: as solicitações em lote são atômicas. Se uma única operação no lote falhar (por exemplo, uma região não for criada), todo o lote vai falhar, e nenhuma mudança será feita. A API vai retornar um erro detalhando a causa da falha.
- Limites de lote: cada solicitação em lote pode conter um máximo de 100 operações de região.
- Cotas: esses endpoints usam os mesmos grupos de cotas que os equivalentes de operação única (
regions.create,regions.delete,regions.update).
Erros e problemas comuns
Confira alguns problemas comuns e as soluções deles.
"O número de solicitações em um lote é muito grande"
Esse erro ocorre se o número de operações na matriz de solicitações exceder o limite de 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Para corrigir isso, divida as operações em várias solicitações em lote de 100 ou menos.
Campo obrigatório ausente.
Esse erro ocorre quando um campo obrigatório está ausente. A mensagem de erro especifica o parâmetro ausente.
As mensagens de erro são as seguintes:
- Para
batchCreate:[regionId] Required parameter: regionId - Para
batchUpdate:[region.name] Required field not provided. - Para
batchDelete:[name] Required parameter: name
Para corrigir isso, verifique se todos os campos obrigatórios estão presentes em cada operação. Por
exemplo, cada entrada em uma solicitação batchUpdate precisa incluir o region.name.
Postar a solicitação a seguir resulta em um erro:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"A região com o ID especificado já existe"
Um erro vai ocorrer se você tentar criar uma região com um regionId que já existe.
A mensagem de erro é [regionId] Region with specified id already exists..
Para corrigir isso, verifique se todos os valores regionId são exclusivos no lote e não entram em conflito com as regiões atuais.
"Valor duplicado encontrado para o campo region.name ou regionId"
Um erro vai ocorrer se você tentar criar ou atualizar várias regiões com o mesmo ID em uma única solicitação em lote.
A mensagem de erro é Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Para corrigir isso, verifique se todos os valores de regionId (para batchCreate) ou region.name (para batchUpdate) são exclusivos em uma única solicitação em lote.
"Item não encontrado"
Ao usar batchUpdate, se alguma região especificada na solicitação não existir,
todo o lote vai falhar com um erro 404 NOT_FOUND. Isso é diferente de
batchDelete, que é bem-sucedido para regiões inexistentes.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Para corrigir isso, verifique se todas as regiões que você está tentando atualizar existem antes de enviar a solicitação.