Zboží třetí strany API

API se používá k přenosu informací o objednávkách mezi Slevovým automatem a systémem obchodního partnera. API vyžaduje implementaci obousměrné komunikace – systém Slevového automatu volá API partnera a partner volá API Slevového automatu.

Objednávky exportované do partnerského API již nelze v partnerském rozhraní Zlavomat upravovat, pouze prohlížet. Exportované objednávky lze nyní upravovat pouze prostřednictvím API.

Všechny požadavky musí být zasílány přes HTTPS a všechna data jsou ve formátu JSON.

Přístupnost API

K API se dostanete na kartě Nastavení v partnerském rozhraní. Pro načtení dat musíte zadat kořenovou URL adresu partnerské části API pro použití ve směru Zlavomat → Partner, např.

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

Přístupové údaje se zobrazí pouze při přístupu k API, proto je uchovávejte v bezpečí.

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

Počáteční export dat

Pro převod stávajících objednávek v okamžiku zpřístupnění API je možné v partnerském rozhraní použít jednorázový export do CSV.

Pokud již máte ve svém systému existující objednávky (vytvořené před zpřístupněním API) a chcete s nimi začít pracovat přes API, použijte funkci „Začít pracovat s označenými objednávkami přes API“ v nabídce „Hromadné akce s objednávkami“.

Popis běžných HTTP odpovědí

• 200 OK – požadavek byl úspěšně zpracován
• 204 No Content – požadavek byl úspěšně zpracován, odpověď nemá žádný obsah
• 400 Bad Request – požadavek není platný – mohou chybět nebo být neplatné parametry v porovnání se specifikací
• 403 Forbidden – autorizace klienta selhala
• 404 Not Found – koncový bod nebo požadovaná data nenalezena
• 405 Method Not Allowed – koncový bod nepodporuje tuto metodu protokolu HTTP
• 422 Unprocessable Entity – očekávaná chyba při zpracování požadavku (viz sekce Chybové stavy )
• 500 Internal Server Error – na straně serveru došlo k chybě
• 502 Bad Gateway – na straně serveru došlo k chybě
• 503 Service Unavailable – server je v režimu údržby (může probíhat nasazení nové verze nebo plánovaný výpadek)
• 504 Gateway Timeout – na straně serveru došlo k chybě

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

V případě chyb4xx V odchozím požadavku je chyba a před dalším pokusem je třeba ji opravit.

Chyby5xx indikují chyby serveru a požadavek lze opakovat beze změny. V případě503 Volající by měl respektovat hlavičku odpovědiRetry-After a další pokus opakujte až po uplynutí času uvedeného v záhlaví.

Stavy objednávek

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

O jakékoli změně stavu je zákazník informován e‑mailem.

Objednávka nemusí nutně projít všemi stavy, aby byla úspěšně doručena; ze stavu „Nová zaplacená objednávka“ je možné přejít rovnou do stavu „Na cestě“ / „Připraveno k osobnímu vyzvednutí“ a poté do stavu „Doručeno zákazníkovi – čeká se na potvrzení zákazníkem“. Využití všech stavů však vede k lepší informovanosti zákazníka o průběhu objednávky a doporučujeme ho.

Chybové stavy

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

Ochutnat:

{ "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 popsány pro konkrétní koncové body. Pokud není uvedeno jinak, hodnota je v uvozovkách."" je vždy povinný řetězec. Pokud není uvedeno jinak, číselná hodnota je vždy povinné celé číslo.

Komunikační slevový automat ⇒ Partner

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

Požadovaná kořenová URL adresa API bude sdílena partnerem a měla by být ve formátu

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

Autorizace požadavků

Když je API zapnuté, partner obdržípartner_api_se­cret , což dokazuje, že příchozí požadavky skutečně pocházejí ze Zlavomatu.

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

Testovací rozhraní

Slevový automat obsahuje funkci pro volání API na straně partnera a zobrazení odpovědi. Kořenová URL adresa zadaná partnerem při zpřístupnění API je připojena k-test , takže v rámci testování je API voláno například na adrese

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

aby se zabránilo míchání testovacích dat s aktivními objednávkami.

Testování partnerského API se provádí pomocí POST požadavků na následující adresy:

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Nová objednávka

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Potvrzení o doručení

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Odmítnutí přijetí

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Zrušit

Část URL adresy<orderId> nahraďte libovolným číslem objednávky, požadavky na partnerské API se odesílají s tímto číslem objednávky.

Požadavky na toto testovací rozhraní musí být autorizovány pomocí hlaviček.X-PartnerToken aX-ApiSecret .

Při testování volání partnerského API systém odešle hlavičkuX-PartnerApiSecret stejně jako v živém provozu.

Data odesílaná s novou objednávkou mají testovací charakter a jsou generována náhodně.

V případě odeslání zrušení objednávky je nutné do těla POST požadavku zahrnout pole JSON.items (ve stejném formátu, jaký odesílá API), které testovací rozhraní ověří a přepošle partnerskému API ve stejné podobě.

Nová objednávka

Žádost obsahuje data nově vytvořené objednávky.

Objednávky jsou vždy jedinečnézlavomatId Pokud se do API dostane duplikátzlavomatId , partnerské API by mělo požadavek ignorovat (první požadavek od Zľavomatu byl vyhodnocen jako neúspěšný, a proto jej opakujeme) a také odpovědět HTTP 204.

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

productId obsahuje ID akce, variantId ID zakoupené varianty.

VolitelnýinternalId znamená interní ID zadané pro variantu akce při jejím vytváření v partnerském rozhraní. Slouží k identifikaci produktu v partnerském systému.

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

VshippingAddress (dodací adresa) je volitelná společnost (company ). V případě doručení na adresushippingAddress obsahuje adresu zákazníka, v případě osobního odběru adresu prodejny, kde si zákazník zboží vyzvedne.

Klíčdelivery .type může nabývat hodnotaddress (doručení na adresu) nebopickup (osobní odběr).delivery .name obsahuje název přepravy nebo název operace.

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

Klíčweight obsahuje hmotnost objednávky v kilogramech. Pokud neznáme hmotnost všech položek v objednávce, nabývá hodnotynull .

POST /objednávka/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "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–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /objednávka/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "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–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Hromadná aktualizace očekávaných termínů dodání

Pokud správce obchodů na žádost partnera hromadně posune data odeslání vybraných objednávek, systém o této aktualizaci informuje partnerské API.

Odeslaná data obsahují pole s ID objednávky a novým očekávaným datem odeslání.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Zrušit

Storna lze vytvářet jak na straně Zlavomatu, tak i na partnerském systému. Tento koncový bod zajišťuje vytváření stornů na straně Zlavomatu a jejich přenos do partnerského systému.

Vytvoří stornování položek objednávky v zadaném množství. Pokud má být stornována celá objednávka, zobrazí se všechny položky s odpovídajícím množstvím.

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

Zrušení (note ) je volitelné.

POST /order/$slevo­matId/cancel

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

Potvrzení o doručení

Poté, co označíte objednávku jako „Doručeno zákazníkovi“, požádáme zákazníka o potvrzení, že ji skutečně obdržel. Když je objednávka označena jako přijatá, bude tento koncový bod volán.

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

{}

Odmítnutí přijetí

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 vyzvednutí“

Tento koncový bod bude volán, pokud byl předchozí stav „Příprava k osobnímu vyzvednutí“ nastaven naautoMarkRea­dyForPickuptrue a na straně Zlavomatu byla objednávka automaticky přepnuta do stavu „Připraveno k osobnímu vyzvednutí“

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

{}

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

Tento koncový bod bude volán, pokud byl předchozí stav nastaven na „Na cestě“, „Příprava k osobnímu vyzvednutí“ nebo „Připraveno k osobnímu vyzvednutí“ sautoMarkDeli­veredtrue a na straně Zlavomatu byla objednávka automaticky přepnuta do stavu „Doručeno zákazníkovi – čeká na potvrzení zákazníkem“.

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

{}

Komunikační partner ⇒ Slevový automat

Tato část API je implementována na straně Zľavomatu a je volána partnerským systémem.

Kořenová adresa URL API je

https://www.zlavomat.sk/zbozi-api/v1

PHP knihovna

Pro implementaci této API stránky můžete použít hotovou PHP knihovnu. Knihovna aktuálně vyžaduje PHP verze 5.4 nebo vyšší a předpokládá použití nástroje Composer.

Pokyny a zdrojový kód knihovny jsou na GitHubu .

Autorizace požadavků

Když je API zapnuté, partner obdržípartner_token aapi_secret , který se používá k prokázání při volání API Zlavomat.

Tyto parametry se předávají v hlavičkáchX-PartnerToken aX-ApiSecret .

Testovací rozhraní

Kořenová URL adresa testovacího rozhraní je

https://www.zlavomat.sk/zbozi-api/v1-test

Je možné na něm volat všechny akce stejně jako na druhém rozhraní.

Testovací rozhraní kontroluje autorizaci požadavků (správnost partnerského tokenu a API tajného kódu) a platnost příchozích těl požadavků (JSON). V těchto ohledech se chová identicky jako živé API.

Testovací rozhraní však nefunguje se skutečnými objednávkami. Neověřuje, zda objednávka přechází mezi správnými stavy a zda obsahuje položky s danými ID. Jakmile proběhne autorizace a ověření formuláře požadavku, testovací rozhraní vždy odpoví kódem úspěšnosti 200 nebo 204.

Vytvořit zrušení

Vytvořte položky pro zrušení objednávky v zadaném množství. Pokud má být zrušena celá objednávka, zobrazí se všechny položky s odpovídajícím množstvím.

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

Zrušení (note ) je volitelné.

POST /order/$slevomatId/cancel

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

Změna stavu objednávky na „Zpracovává se“

POST /order/$slevomatId/mark-pending

{}

Změna stavu objednávky na „Na cestě“

Při objednávání je parametrautoMarkDelivered určit, zda se má stav po uplynutí nastavené přepravní doby („Doba od odeslání do doručení“) automaticky změnit na „Doručeno zákazníkovi – čeká se na potvrzení zákazníkem“

Odpověď obsahuje aktualizovaný odhadovaný termín doručení.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Odpověď 200

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

Změna stavu objednávky na „Příprava k osobnímu vyzvednutí“

Při objednávání je parametrautoMarkReady­ForPickup určit, zda se má stav automaticky změnit na „Připraveno k osobnímu vyzvednutí“ po uplynutí doby od odeslání do doručení pro daný typ výdejního místa.

Při objednávání je parametrautoMarkDelivered určit, zda se má stav automaticky změnit z „Připraveno k osobnímu vyzvednutí“ na „Doručeno zákazníkovi – čeká se na potvrzení zákazníkem“ po uplynutí nastaveného počtu dnů pro vyzvednutí na daném typu odběrného místa.

Kombinace parametrůautoMarkReady­ForPickup falešné aautoMarkDelivered Hodnota true není povolena. V tomto případě je vrácen kód chyby 9.

Odpověď obsahuje aktualizovaný odhadovaný termín doručení.

POŠTA /objednávka/$slevomatId/označit-připravu-k-vyzvednutí

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

Odpověď 200

{ "expectedDeli­veryDate": "2021–09–06" }

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

Při objednávání je parametrautoMarkDelivered určit, zda se má stav automaticky změnit na „Doručeno zákazníkovi – čeká se na potvrzení zákazníkem“ po uplynutí nastaveného počtu dnů pro vyzvednutí pro daný typ sběrného místa.

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

{ "autoMarkDeli­vered": true }

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

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

{}

Změna dodací adresy

Dodací adresu lze změnit pouze při doručování na adresu (tj. místo podobného vyzvednutí nelze změnit).

Všechny klávesy kroměcompany jsou povinné.

Platné hodnoty pro klíčstate jsoucz (Česká republika) ask (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" }