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.
L'API Merchant fournit des points de terminaison par lot pour gérer vos régions. Vous pouvez ainsi créer, modifier et supprimer jusqu'à 100 régions en un seul appel d'API. Cette solution 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 Batch vous permet d'effectuer les actions suivantes avec les méthodes associées :
- Créer plusieurs régions dans une même requête :
regions:batchCreate - Supprimer plusieurs régions à la fois :
regions:batchDelete - Mettez à 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 un 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 displayName et postalCodeArea pour 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 à modifier (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 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 renverra une erreur expliquant la cause de l'échec.
- Limites de lot : chaque requête par lot peut contenir 100 opérations régionales 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 les solutions correspondantes.
"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 opérations ou moins.
Un champ obligatoire n'est pas renseigné.
Cette erreur se produit lorsqu'un champ obligatoire est manquant. Le message d'erreur indique le paramètre manquant.
Voici les messages d'erreur :
- 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 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"
}
]
}
"Une région portant cet ID 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 le suivant : [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.
"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 même requête par lot.
Le message d'erreur est le suivant : 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 même requête par lot.
"Élément introuvable"
Lorsque vous utilisez batchUpdate, si l'une des régions spécifiées dans la requête n'existe pas, l'ensemble du lot échoue et une erreur 404 NOT_FOUND s'affiche. Cette méthode est différente 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.