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 códigos postais ou, em alguns países, usando geotargets predefinidos. Para mais informações, consulte Configurar
regiões.
A API Merchant oferece endpoints em lote para gerenciar suas regiões, permitindo criar, atualizar e excluir até 100 regiões em uma única chamada de API. Isso é ideal para comerciantes que gerenciam a disponibilidade e os preços regionais (RAAP, na sigla em inglês) em grande escala, melhorando a eficiência e simplificando a integração.
Visão geral
A API Batch permite que você faça 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 o papel 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
Construa 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 o displayName e o postalCodeArea de duas regiões. Você precisa fornecer um region.name para atualizar a região segmentada.
Solicitação
Construa 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. A inclusão de updateMask para indicar os campos a serem alterados é 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, tenha estas regras em mente:
- Operações atômicas: as solicitações em lote são atômicas. Se qualquer operação individual no lote falhar (por exemplo, uma região não for criada), o lote inteiro 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 as contrapartes 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.
A postagem da solicitação a seguir resulta em um erro:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Já existe uma região com o ID especificado"
Um erro ocorre 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 ocorre 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 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.