Aller au contenu

Connecter votre propre logiciel avec l’API ​

Avec l’API, vos développeurs connectent n’importe quel système pour lequel la marketplace n’a pas d’application : vous envoyez vos produits, prix, stock et suivis, et la marketplace vous envoie chaque commande sur un webhook.

Connecter ​

  1. Dans Settings > Integrations, choisissez API : votre clé API y est affichée
  2. Envoyez à votre marketplace l’URL du webhook qui recevra vos commandes : vous recevez en retour le secret de webhook qui les signe

Chaque requête est un POST vers une seule adresse, avec votre clé et un sujet :

POST https://webhooks.garnetmarketplace.com/sellers/api
Authorization: Bearer your_api_key
X-Garnet-Topic: products/update
Content-Type: application/json

Chaque requête est vérifiée et reçoit la réponse 202 Accepted, puis est appliquée en quelques secondes. Une requête refusée reçoit 400 avec la liste de ce qui ne va pas : { "error": ["variants[0].price must be a number"] }.

Produits : products/update ​

Crée le produit, ou met à jour celui que vous avez envoyé auparavant avec le même externalId :

json
{
  "externalId": "tallow-soap-1",
  "title": "Tallow Soap",
  "descriptionHtml": "<p>Handmade tallow soap.</p>",
  "productType": "Soap",
  "tags": ["handmade"],
  "variants": [{ "sku": "SOAP-1", "price": 12, "inventoryQuantity": 20, "weight": { "value": 120, "unit": "GRAMS" } }],
  "images": [{ "src": "https://example.com/soap.jpg", "alt": "Tallow soap" }]
}

Chaque variante a besoin d’un sku et d’un price ; elle peut aussi avoir compareAtPrice, barcode, tracked (stock suivi, true par défaut) et requiresShipping (true par défaut). L’unit du poids est GRAMS, KILOGRAMS, OUNCES ou POUNDS. Pour des tailles ou des couleurs, listez-les dans "productOptions": [{ "name": "Size", "values": ["S", "M"] }] et donnez à chaque variante ses "optionValues": [{ "optionName": "Size", "name": "S" }].

Un produit que vous avez déjà ajouté dans l’application est repris par son SKU lors de son premier envoi : l’envoi le met alors à jour, titre, description et images compris, au lieu d’en créer un second.

Prix et stock : inventory/update ​

Jusqu’à 250 variantes par SKU : [{ "sku": "SOAP-1", "price": 12, "stock": 18 }]. Un SKU que la marketplace n’a pas est ignoré.

Commandes : votre webhook ​

Chaque commande contenant vos produits est envoyée à votre webhook en POST avec X-Garnet-Topic: orders/create, au format de commande de Shopify, avec vos articles uniquement. Répondez par un 2xx. Vérifiez qu’elle vient de la marketplace : le HMAC-SHA256 du corps brut, avec votre secret de webhook comme clé et encodé en base64, doit être égal à l’en-tête X-Garnet-Hmac-Sha256.

Suivi : fulfillments/create ​

Quand vous expédiez, envoyez l’id de la commande reçu par le webhook : { "orderId": 5538456789012, "trackingNumber": "1Z999AA10123456784", "trackingCompany": "UPS", "trackingUrl": "https://…" }. La commande est expédiée et le client prévenu.

Tester ​

Il n’y a pas d’environnement de test : demandez à votre marketplace une commande de test, avec une remise de 100 % par exemple. Elle arrive sur votre webhook comme les autres, et votre suivi l’expédie.

Si cela ne fonctionne pas ​

  • 401 : la clé est fausse, ou envoyée sans Bearer.
  • 202 mais rien ne change : l’externalId du produit ou le SKU ne correspond pas à ce que vous avez envoyé auparavant.
  • 202 mais le produit n’apparaît jamais : un nouveau produit sans stock n’est pas importé, sauf si votre marketplace importe les produits en rupture. Envoyez inventoryQuantity sur chaque variante (ou tracked: false) et renvoyez le produit.
  • Aucune commande n’arrive : l’URL du webhook n’est pas encore enregistrée, est fausse ou n’est pas publique, ou la commande ne contient aucun de vos produits.

Demandez à votre marketplace ​

Si elle importe tous vos produits ou les sélectionne, et pour enregistrer ou modifier l’URL de votre webhook.