Avant d'utiliser la ressource orders, suivez les étapes de la section Premiers pas avec la ressource Orders.
Pour effectuer une transaction simple à l'aide de la ressource Orders :
- Créez une commande.
- Faites avancer l'état de la commande.
- Listez toutes les commandes.
- Confirmez la commande.
- Attribuez un ID marchand de commande.
- Débitez le client.
- Créez un envoi.
- Mettez à jour l'état de la commande.
Tous les exemples utilisent le mode sandbox en spécifiant /v2.1sandbox dans l'URL. Vous pouvez supprimer sandbox pour exécuter les exemples dans un environnement de production avec /v2.1.
Créer une commande
Assurez-vous de pouvoir vous connecter à votre compte Merchant Center via la ressource Orders. Utilisez ensuite createtestorder avec l'URL suivante et un modèle de commande pour créer une commande en mode sandbox.
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders
{
"templateName": "template1"
}
Si l'appel aboutit, l'ID orderId de la nouvelle commande est renvoyé :
{
"kind": "content#ordersCreateTestOrderResponse",
"orderId": "G-PLA-7877-86-2240"
}
(Mode sandbox uniquement) Faire avancer l'état de la commande
Les commandes approuvées ont l'état pendingShipment. En mode production, l'état de la commande est automatiquement mis à jour. En mode sandbox, vous devez le définir vous-même sur pendingShipment.
Pour définir l'état d'une commande sur pendingShipment, appelez advancetestorder :
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders/order_ID/advance
Voici un exemple d'appel :
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders/G-PLA-7877-86-2240/advance
{
"orderId": "G-PLA-7877-86-2240"
}
Pour vérifier que l'état de la commande est à jour, utilisez get :
GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240
Lister toutes les commandes
Vous pouvez utiliser list pour lister toutes vos commandes actuelles :
GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/
Nous vous recommandons d'appeler cette méthode toutes les 10 minutes.
Vous pouvez ajouter acknowledged=false à un appel list pour ne lister que les commandes qui n'ont pas encore été confirmées :
GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/?acknowledged=false
Confirmer la commande
Vous pouvez utiliser acknowledge pour définir l'état de la commande sur acknowledged :
L'appel acknowledge nécessite un appel operationId que vous pouvez utiliser pour réexécuter des requêtes et empêcher les opérations en double. Vous définissez vous-même la valeur operationId.
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/acknowledge
{
"operationId": "operation-1"
}
Attribuer un ID marchand de commande
Après avoir confirmé une commande, vous pouvez lui attribuer un ID marchand de commande avec updatemerchantorderid. Il y a une seule consigne à respecter : la valeur attribuée doit être unique au sein de votre compte Merchant Center. Nous vous recommandons d'utiliser le même ID de commande que celui de votre système de gestion des commandes.
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateMerchantOrderId
{
"operationId": "operation-2",
"merchantOrderId": "unique_value_within_mc_account"
}
Après avoir attribué un ID marchand de commande, vous pouvez exécuter une requête pour une commande spécifique à l'aide de getbymerchantorderid.
Débiter le client
Vous pouvez éventuellement appeler captureOrder pour débiter le client avant d'expédier la commande. Il vous suffit d'appeler captureOrder une seule fois par commande.
Notez que le fait de débiter un client n'entraîne pas le versement immédiat du paiement sur votre compte.
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/captureOrder
captureOrder indique si le client a été débité ou non.
En cas de réussite, vous pouvez expédier la commande. En cas d'échec, le problème provient peut-être de la facturation du client ou du marchand. Vous pouvez annuler (cancel) la commande au lieu de l'expédier ou bien réessayer plus tard.
Créer un envoi
Vous pouvez créer un envoi avec shiplineitems.
Vous devez inclure les éléments suivants dans le corps de la requête :
shipmentId- Identifiant de l'envoi.
operationId- Identifiant que vous choisissez lorsque vous confirmez une commande.
lineItems[].lineItemId- ID d'article issu de la ressource Orders dans la réponse à un appel
getoulist. lineItems[].quantity- Nombre d'articles expédiés. La valeur doit être supérieure ou égale à 1.
Lorsque l'API crée un envoi, elle définit l'état de la commande sur shipped si tous les articles sont expédiés ou sur partiallyShipped si seuls certains d'entre eux le sont.
Voici un exemple d'appel shiplineitems :
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/shipLineItems
{
"operationId": "operation-4",
"shipmentId": "shipment-1",
"lineItems": [
{
"lineItemId": "CYBIDQWXDKCZEYE",
"quantity": 1
}
],
"carrier": "FedEx",
"trackingId": "ASDFGHJKL12347890"
}
Mettre à jour l'état de la commande
Lorsque le ou les envois sont arrivés, vous pouvez mettre à jour leur état sur delivered avec updateshipment.
Utilisez le shipmentId que vous avez défini lors de la création de l'envoi avec shiplineitems. Vous pouvez retrouver le shipmentID dans la réponse de get une fois la commande expédiée.
Voici un exemple d'appel updateshipment :
POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateShipment
{
"operationId": "operation-5",
"shipmentId": "shipment-1",
"status": "delivered"
}
À ce stade, la commande est terminée.
Vous pouvez explorer les autres appels disponibles dans la documentation de référence et en savoir plus sur les problèmes connus dans la section Limites et contraintes.