Une région Merchant API représente une région géographique que vous pouvez utiliser comme cible associée à la ressource accounts.products.regionalInventories. Vous pouvez définir des régions comme des ensembles de codes postaux ou, dans certains pays, à l'aide de cibles géographiques prédéfinies. Pour en savoir plus, consultez Configurer
des régions.
Merchant API fournit des points de terminaison par lot pour gérer vos régions. Vous pouvez ainsi créer, mettre à jour et supprimer jusqu'à 100 régions en un seul appel d'API. Cette fonctionnalité est idéale pour les marchands qui gèrent la disponibilité et la tarification selon la région à grande échelle, car elle améliore l'efficacité et simplifie l'intégration.
Présentation
L'API par lot vous permet d'effectuer les opérations suivantes avec les méthodes associées :
- Créer plusieurs régions en une seule requête :
regions:batchCreate - Supprimer plusieurs régions à la fois :
regions:batchDelete - Mettre à jour plusieurs régions simultanément :
regions:batchUpdate
Prérequis
Toutes les requêtes par lot nécessitent le rôle utilisateur ADMIN pour l'authentification.
Créer plusieurs régions
Cet exemple montre comment créer deux régions : l'une définie par des codes postaux et l'autre par ciblage géographique, en un seul appel de BatchCreateRegions.
Requête
Créez l'URL de la requête comme suit :
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Le corps de la requête contient une liste de requests, où chaque objet spécifie un
regionId et les données region à créer.
{
"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"
]
}
}
}
]
}
Réponse
Une requête réussie renvoie une liste des nouveaux objets 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
}
]
}
Mettre à jour plusieurs régions
Cet exemple montre comment utiliser BatchUpdateRegions pour mettre à jour les displayName et postalCodeArea de deux régions existantes. Vous devez fournir un region.name pour mettre à jour la région ciblée.
Requête
Créez l'URL de la requête comme suit :
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Le corps de la requête contient une liste de requests. Chaque objet doit spécifier les données region à mettre à jour. Le champ region.name doit contenir l'ID de la région à mettre à jour, par exemple "98005". Spécifiez la ressource en tant que name plutôt
que accounts/{ACCOUNT_ID}/regions/name. L'inclusion de updateMask pour indiquer les champs à modifier est facultative.
{
"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"
}
]
}
Réponse
Une requête réussie renvoie une liste des objets region mis à jour.
{
"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
}
]
}
Supprimer plusieurs régions
Vous pouvez supprimer plusieurs régions en un seul appel.
Requête
Cet exemple montre comment utiliser BatchDeleteRegions pour supprimer deux régions en un seul appel.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Le corps de la requête contient une liste de requests, où chaque objet spécifie le
name (sans "accounts/{ACCOUNT_ID}/regions/") de la région à supprimer.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Réponse
Une requête réussie renvoie un corps de réponse vide, indiquant que les régions spécifiées ont été supprimées (ou n'existaient pas).
{}
Limites
Avant de commencer, gardez à l'esprit les règles suivantes :
- Opérations atomiques : les requêtes par lot sont atomiques. Si une seule opération du lot échoue (par exemple, si une région ne peut pas être créée), l' ensemble du lot échoue et aucune modification n'est apportée. L'API renvoie une erreur détaillant la cause de l'échec.
- Limites de lot : chaque requête par lot peut contenir 100 opérations de région au maximum.
- Quotas : ces points de terminaison utilisent les mêmes groupes de quotas que leurs
homologues à opération unique (
regions.create,regions.delete,regions.update).
Erreurs et problèmes courants
Voici quelques pièges courants et leurs solutions.
"The number of requests in a batch is too large" (Le nombre de requêtes dans un lot est trop élevé)
Cette erreur se produit si le nombre d'opérations dans votre tableau de requêtes dépasse la limite de 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Pour résoudre ce problème, divisez vos opérations en plusieurs requêtes par lot de 100 ou moins.
Un champ obligatoire n'est pas renseigné.
Cette erreur se produit lorsqu'un champ obligatoire est manquant. Le message d'erreur spécifie le paramètre manquant.
Les messages d'erreur sont les suivants :
- Pour
batchCreate:[regionId] Required parameter: regionId - Pour
batchUpdate:[region.name] Required field not provided. - Pour
batchDelete:[name] Required parameter: name
Pour résoudre ce problème, vérifiez que tous les champs obligatoires sont présents dans chaque opération. Par exemple, chaque entrée d'une requête batchUpdate doit inclure le region.name.
L'envoi de la requête suivante génère une erreur :
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Region with specified ID already exists" (Une région avec l'ID spécifié existe déjà)
Une erreur se produit si vous essayez de créer une région avec un regionId qui existe déjà.
Le message d'erreur est [regionId] Region with specified id already exists..
Pour résoudre ce problème, vérifiez que toutes les valeurs regionId sont uniques dans le lot et qu'elles ne sont pas en conflit avec les régions existantes.
"Duplicate value found for field region.name or regionId found" (Valeur en double détectée pour le champ region.name ou regionId)
Une erreur se produit si vous essayez de créer ou de mettre à jour plusieurs régions avec le même ID dans une seule requête par lot.
Le message d'erreur est Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Pour résoudre ce problème, vérifiez que toutes les valeurs regionId (pour batchCreate) ou region.name (pour batchUpdate) sont uniques dans une seule requête par lot.
"Item not found" (Élément introuvable)
Lorsque vous utilisez batchUpdate, si une région spécifiée dans la requête n'existe pas, l'ensemble du lot échoue avec une erreur 404 NOT_FOUND. Cela diffère de batchDelete, qui réussit pour les régions inexistantes.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Pour résoudre ce problème, vérifiez que toutes les régions que vous tentez de mettre à jour existent avant d'envoyer la requête.