PARTNERSKÝ PRŮVODCE
Čeština Němčina Angličtina Chorvatština Maďarština Italština Polština Ruština Slovenština Slovinština Ukrajinština Vietnamština
Úvod Praktické návody IT podpora API Zboží 3. stran

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

Zpět na výpis článků

Související články

Nahoru