API Zboží 3. stran

API slouží k přenosu informací o objednávkách mezi Slevomatem a systémem obchodního partnera. API vyžaduje implementaci oboustranné komunikace – systém Slevomatu volá API partnera a partner volá API Slevomatu.

S objednávkami exportovanými do partnerského API již není možné manipulovat v partnerském rozhraní Slevomatu, pouze je prohlížet. Manipulace s exportovanými objednávkami už může probíhat pouze přes API.

Všechny požadavky musí být prováděny na HTTPS a veškerá data jsou ve formátu JSON.

Zpřístupnění API

Přístupové údaje k API získáte v záložce Nastavení ve vašem partnerském rozhraní. Pro získání údajů je třeba poskytnout kořenovou URL partnerské části API pro použití ve směru Slevomat → Partner, např.

https://example­.com/slevomat-zbozi-api 

Přístupové údaje se zobrazí pouze jednou při zpřístupnění API, pečlivě si je uschovejte.

Jakmile je API zpřístupněné, nově vytvořené objednávky do něj systém začne exportovat.

Prvotní export dat

Pro přelití již případně existujících objednávek v momentě zpřístupnění API lze využít jednorázový export do CSV v partnerském rozhraní.

V momentě, kdy máte již existující objednávky (vzniklé před zpřístupněním API) ve vlastním systému a chcete zahájit práci s nimi přes API, použijte funkci „Zahájit práci s označenými objednávkami přes API“ v menu „Hromadné akce s objednávkami“.

Popis obvyklých HTTP responses

• 200 OK – požadavek byl úspěšně zpracován
• 204 No Content – požadavek byl zpracován, odpověď nemá žádný obsah
• 400 Bad Request – požadavek není validní – může se jednat o chybějící nebo nevalidní parametry vůči specifikaci
• 403 Forbidden – selhala autorizace klienta
• 404 Not Found – nenalezený endpoint nebo požadovaná data
• 405 Method Not Allowed – endpoint nepodporuje tuto HTTP metodu
• 422 Unprocessable Entity – očekávaná chyba při zpracování požadavku (viz sekce Chybové stavy)
• 500 Internal Server Error – došlo k chybě na straně serveru
• 502 Bad Gateway – došlo k chybě na straně serveru
• 503 Service Unavailable – server je v maintenance módu (může probíhat deploy nové verze, nebo plánovaná odstávka)
• 504 Gateway Timeout – došlo k chybě na straně serveru

Odpovědi HTTP 5×x nemusí používat formát JSON.

V případě chyb 4xx je chyba v odchozím požadavku a před opakováním pokusu je třeba ho opravit.

Chyby 5xx značí chyby serveru a požadavek lze opakovat bez jeho změny. V případě 503 by volající měl respektovat hlavičku odpovědi Retry-After a další pokus opakovat až po uplynutí doby uvedené v hlavičce.

Stavy objednávky

Objednávka je vždy v jednom z následujících stavů:

Hodnota stavu	Popis
1	Nová zaplacená objednávka
2	Vyřizuje se
3	Zboží odesláno (pouze objednávky s dopravou)
4	Připravuje se k osobnímu odběru – např. probíhá přeprava na pobočku
5	Připraveno k osobnímu odběru
6	Doručeno zákazníkovi – čeká na potvrzení zákazníkem
7	Doručeno a potvrzeno zákazníkem
8	Zákazník odmítl potvrdit převzetí objednávky
9	Stornovaná objednávka

O každé změně stavu je zákazník informován e‑mailem.

Objednávka nemusí nutně projít všemi stavy k úspěšnému doručení, z „Nová zaplacená objednávka“ lze přejít rovnou do „Zboží odesláno“ / „Připraveno k osobnímu odběru“ a poté do „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“. Využití všech stavů ovšem vede k lepší informovanosti zákazníka o průběhu vyřizování objednávky a doporučujeme ho.

Chybové stavy

V případě HTTP kódů 4×x odpověď vždy obsahuje klíč status (viz číselník níže) a pole messages s textovými popisy chyb.

Hodnota stavu	Popis
1	Nevalidní požadavek – chybějící nebo nevalidní hodnoty
2	Neplatné přihlašovací údaje
3	Neexistující objednávka
4	Neexistující položka objednávky
5	Přechod objednávky do nepovoleného stavu
6	Neplatné storno – stornování většího počtu položek, než existuje
7	Jiná chyba
8	Objednávka nebyla ještě exportována do partnerského API – nelze s ní skrze API manipulovat
9	Pro automatické nastavení stavu „Zboží doručeno zákazníkovi“ je třeba zásilku nechat automaticky nastavit do stavu „Zboží připraveno k vyzvednutí“

Ukázka:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Datové typy

Datové typy jednotlivých klíčů v požadavcích a odpovědích jsou vždy popsané u konkrétních endpointů. Pokud není uvedeno jinak, hodnota v uvozovkách "" je vždy povinný string. Pokud není uvedeno jinak, číselná hodnota je vždy povinný integer.

Komunikace Slevomat ⇒ Partner

Tato část API je implementována na straně partnera a Slevomat ji volá.

Požadovanou kořenovou URL API sdělí partner, měla by být ve tvaru

 https://www.example.com/slevomat-zbozi-api/v1

Autorizace požadavků

Při zapnutí API partner obdrží partner_api_se­cret, kterým se příchozí požadavky prokazují, že pochází opravdu od Slevomatu.

Tento parametr je předáván v HTTP hlavičce X-PartnerApiSecret.

Testovací rozhraní

Slevomat obsahuje funkcionalitu na provolání API na partnerské straně a zobrazení odpovědi. Ke kořenové URL uvedené partnerem při zpřístupnění API je připojeno -test, takže v rámci testování je provoláváno API na adrese např.

https://example­.com/slevomat-zbozi-api-test

aby nedošlo k promíchání testovacích dat s ostrými objednávkami.

Testování partnerského API probíhá pomocí POST požadavků na následující adresy:

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

  – Nová objednávka

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

  – Hromadná aktualizace očekávaných dat odeslání

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

  – Změna stavu objednávky na „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

  – Změna stavu objednávky na „Připraveno k osobnímu odběru“

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

  – Potvrzení doručení

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

  – Odmítnutí převzetí

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

  – Storno

Část URL <orderId> nahraďte za libovolné číslo objednávky, s tímto číslem objednávky jsou prováděny požadavky na partnerské API.

Požadavky na toto testovací rozhraní je potřeba autorizovat hlavičkami X-PartnerToken a X-ApiSecret.

Při testovacím provolávání partnerského API systém posílá hlavičku X-PartnerApiSecret stejně jako v ostrém provozu.

Data zasílaná s novou objednávkou jsou testovacího charakteru a náhodně generovaná.

V případě zasílání storna objednávky je potřeba v POST tělu požadavku uvést v JSONu pole items (ve stejném formátu jako zasílá API), které testovací rozhraní zvaliduje a partnerskému API přepošle ve stejné podobě.

Nová objednávka

Požadavek obsahuje data nově vytvořené objednávky.

Objednávky mají vždy unikátní slevomatId. Pokud do API přijde duplicitní slevomatId, požadavek by partnerské API mělo ignorovat (první provedený požadavek Slevomat vyhodnotil jako neúspěšný a proto ho opakujeme) a odpovědět taktéž HTTP 204.

created je datum ve formátu ISO 8601, tedy YYYY-MM-DD'T'HH:mm:ss­+zz:zz.

productId obsahuje ID akce, variantId ID zakoupené varianty.

Nepovinné internalId značí interní ID zadávané u varianty akce při jejím vytváření v partnerském rozhraní. Slouží k identifikaci produktu v systému partnera.

V billingAddress (fakturační adresa) je povinné pouze jméno (name) zákazníka.

V shippingAddress (doručovací adresa) je nepovinná firma (company). V případě doručení na adresu shippingAddress obsahuje adresu zákazníka, v případě osobního odběru adresu provozovny, kde si zákazník zboží vyzvedne.

Klíč delivery.type může nabývat hodnoty address (doručení na adresu) nebo pickup (osobní odběr). delivery.name obsahuje název dopravy nebo jméno provozovny.

delivery.expec­tedShippingDa­te (předpokládané datum odeslání) a delivery.expec­tedDeliveryDa­te (předpokládané datum doručení) jsou data ve formátu YYYY-MM-DD.

Klíč weight obsahuje hmotnost objednávky v kilogramech. V případě, že neznáme hmotnost všech položek objednávky, nabývá hodnotu null.

POST /order/$slevomatId

{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /order/$slevomatId

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Hromadná aktualizace očekávaných dat odeslání

V případě, že deals manažer na žádost partnera posune hromadně data odeslání vybraných objednávek, systém informuje partnerské API o této aktualizaci.

Odesílaná data obsahují pole s ID objednávek a nové očekávané datum odeslání.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Storna

Storno lze vytvořit jak na straně Slevomatu tak partnerského systému. Tento endpoint obsluhuje vytvoření storna na straně Slevomatu a jeho přenos do systému partnera.

Vytvoří storno položek objednávky v určeném množství. Pokud má být objednávka stornována celá, jsou uvedeny všechny položky s odpovídajícím množství.

Jednotlivé položky je možné stornovat i částečně (např. 1 kus ze dvou).

Poznámka ke stornu (note) je nepovinná.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Potvrzení doručení

Poté co označíte objednávku jako „Doručeno zákazníkovi“ si vyžádáme od zákazníka potvrzení že ji opravdu převzal. Když je objednávka označena jako převzatá, dojde k provolání tohoto endpointu.

POST /order/$slevo­matId/confirm-delivery

{}

Odmítnutí převzetí

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Změna stavu objednávky na „Připraveno k osobnímu odběru“

K provolání tohoto endpointu dojde v případě, kdy byl předchozí stav „Připravuje se k osobnímu odběru“ nastaven s autoMarkRea­dyForPickuptrue a na straně Slevomatu došlo k automatickému přepnutí objednávky do stavu „Připraveno k osobnímu odběru“

POST /order/$slevo­matId/delivery-ready-for-pickup

{}

Změna stavu objednávky na „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“

K provolání tohoto endpointu dojde v případě, kdy byl předchozí stav „Zboží odesláno“, „Připravuje se k osobnímu odběru“ nebo „Připraveno k osobnímu odběru“ nastaven s autoMarkDeli­veredtrue a na straně Slevomatu došlo k automatickému přepnutí objednávky do stavu „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“.

POST /order/$slevo­matId/mark-delivered

{}

Komunikace Partner ⇒ Slevomat

Tato část API je implementována na straně Slevomat a volá ji partnerský systém.

Kořenná URL API je

 https://www.slevomat.cz/zbozi-api/v1

PHP knihovna

Pro implementaci této strany API lze využít připravenou PHP knihovnu. Knihovna aktuálně vyžaduje verzi PHP 5.4 nebo vyšší a předpokládá využití nástroje Composer.

Návod na použití knihovny a zdrojové kódy jsou na GitHubu.

Autorizace požadavků

Při zapnutí API partner obdrží partner_token a api_secret, kterými se prokazuje při volání API Slevomatu.

Tyto parametry jsou předávány v hlavičkách X-PartnerToken a X-ApiSecret.

Testovací rozhraní

Kořenná URL testovacího rozhraní je

https://www.slevomat.cz/zbozi-api/v1-test

Lze na něm volat všechny akce jako na ostrém rozhraní.

Testovací rozhraní kontroluje autorizaci požadavků (správnost partner tokenu a API secret) a validitu příchozích těl požadavků (JSON). V těchto ohledech se chová shodně s ostrým API.

Testovací rozhraní ovšem nepracuje se skutečnými objednávkami. Nevaliduje tedy, zdali objednávka přechází mezi správnými stavy a jestli obsahuje položky s danými ID. Jakmile projde autorizace a validování formy požadavku, testovací rozhraní vždy odpovídá úspěšný kód 200 nebo 204. 

Vytvoření storna

Vytvoří storno položek objednávky v určeném množství. Pokud má být objednávka stornována celá, jsou uvedeny všechny položky s odpovídajícím množství.

Jednotlivé položky je možné stornovat i částečně (např. 1 kus ze dvou).

Poznámka ke stornu (note) je nepovinná.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Změna stavu objednávky na „Vyřizuje se“

POST /order/$slevo­matId/mark-pending

{}

Změna stavu objednávky na „Zboží odesláno“

U objednávky lze parametrem autoMarkDelivered určit, zdali se po nastavené lhůtě dopravy („Doba od odeslání zboží do doručení“) má automaticky přepnout do stavu „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“.

Odpověď obsahuje aktualizované předpokládané datum doručení.

POST /order/$slevo­matId/mark-en-route

{ "autoMarkDeli­vered": true }

Response 200

{ "expectedDeli­veryDate": "2021–08–25" }

Změna stavu objednávky na „Připravuje se k osobnímu odběru“

U objednávky lze parametrem autoMarkReady­ForPickup určit, zdali se po uplynutí doby od odeslání zboží do doručení u daného typu odběrového místa má automaticky přepnout do stavu „Připraveno k osobnímu odběru“.

U objednávky lze parametrem autoMarkDelivered určit, zdali se po nastavené lhůtě počtu dnů na vyzvednutí u daného typu odběrového místa má automaticky přepnout ze stavu „Připraveno k osobnímu odběru“ do stavu „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“.

Kombinace parametrů autoMarkReady­ForPickup false a autoMarkDelivered true není povolena. V takovém případě se vrátí chybový kód 9. 

Odpověď obsahuje aktualizované předpokládané datum doručení.

POST /order/$slevo­matId/mark-getting-ready-for-pickup

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Response 200

{ "expectedDeli­veryDate": "2021–08–25" }

Změna stavu objednávky na „Připraveno k osobnímu odběru“

U objednávky lze parametrem autoMarkDelivered určit, zdali se po nastavené lhůtě počtu dnů na vyzvednutí u daného typu odběrového místa má automaticky přepnout do stavu „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Změna stavu objednávky na „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“

POST /order/$slevo­matId/mark-delivered

{}

Změna doručovací adresy

Doručovací adresu lze měnit pouze u doručení na adresu (tj. místo osobního odběru měnit nelze).

Všechny klíče kromě company jsou povinné.

Validní hodnoty pro klíč state jsou cz (Česká republika) a sk (Slovensko).

POST /order/$slevo­matId/update-shipping-address

{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Changelog

03. 02. 2016 Popis chybového stavu č. 9 – pro přepínání do stavu „Připravuje se k osobnímu odběru“. 09. 11. 2015 Do nové objednávky přibylo pole pro hmotnost 20. 10. 2015 Přibyl endpoint pro Změnu doručovací adresy 13. 10. 2015 Do fakturační adresy přibylo pole pro stát Do dat nové objednávky byly doplněny ceny zboží a dopravy 24. 9. 2015 API a PHP knihovna verze 1.1  Při volání Odmítnutí převzetí je zasílán důvod odmítnutí zákazníkem Nový endpoint pro hromadnou aktualizaci očekávaných dat odeslání (Slevomat → Partner, update-shipping-dates) 23. 9. 2015 Do testovacího rozhraní směru Slevomat → Partner doplněno provolávání ready-for-pickup – Změna stavu objednávky na „Připraveno k osobnímu odběru“ Data o nové objednávce obsahují nyní název a ID provozovny v novém klíči deliveryPremise. Doplněn příklad dat o nové objednávce s osobním odběrem Položky objednávky v datech o nové objednávce nyní obsahují variantId a productId. – ID varianty a ID akce. 18. 9. 2015 Do dat o nové objednávce doplněn e‑mail zákazníka 17. 9. 2015 Popsána podpora pro automatické přepínání ze stavu „Připravuje se k osobnímu odběru“ do „Připraveno k osobnímu odběru“ Popsána podpora pro automatické přepínání ze stavu „Připraveno k osobnímu odběru“ do „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“ 10. 9. 2015 Zpřístupnění API pomocí samoobslužného formuláře 7. 9. 2015 Upřesnění – Prvotní export dat 1. 9. 2015 Finalizováno verze API 1.0! Popis zpřístupnění API Popis prvotního exportu dat Popis testovacích rozhraní Odkaz na knihovnu pro komunikaci Partner → Slevomat Chybový stav 8  17. 8. 2015 Změna typu slevomat_id (number ⇒ string) Převod na camelCase: slevomat_id ⇒ slevomatId internal_id ⇒ internalId auto-mark-delivered ⇒ autoMarkDelivered 2. 8. 2015: První verze