Français
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
- Dans
Settings > Integrations, choisissezAPI: votre clé API y est affichée - 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/jsonChaque 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 sansBearer.202mais rien ne change : l’externalIddu produit ou le SKU ne correspond pas à ce que vous avez envoyé auparavant.202mais le produit n’apparaît jamais : un nouveau produit sans stock n’est pas importé, sauf si votre marketplace importe les produits en rupture. EnvoyezinventoryQuantitysur chaque variante (outracked: 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.