PARTNERSKÝ SPRIEVODCA
Slovenština Čeština Němčina Angličtina Chorvatština Maďarština Polština Vietnamština
Úvod Praktické návody IT podpora API Tovar 3. strán

API Tovar 3. strán

API slúži k prenosu informácií o objednávkach medzi Zľavomatom a systémom obchodného partnera. API vyžaduje implementáciu obojstrannej komunikácie – systém Zľavomatu volá API partnera a partner volá API Zľavomatu.

S objednávkami exportovanými do partnerského API už nie je možné manipulovať v partnerskom rozhraní Zľavomatu, iba si ich prezerať. Manipulácia s vyexportovanými objednávkami už môže prebiehať iba cez API.

Všetky požiadavky musia byť vykonané na HTTPS a všetky dáta sú vo formáte JSON.

Prístupnosť API

Prístup k rozhraniu API môžete získať na karte Nastavenia vo vašom partnerskom rozhraní. Ak chcete získať údaje, musíte zadať koreňový kód URL partnerskej časti API pre použitie v smere Zľavomat → Partner, napr.

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

Prístupové údaje sa zobrazia iba pri sprístupnení API, dôkladne si ich uchovajte.

Akonáhle je API sprístupnené, novo vytvorené objednávky do ňho systém začne exportovať.

Prvotný export dát

Pre preliatie už existujúcich objednávok v momente sprístupnenia API je možné využiť jednorázový export do CSV v partnerskom rozhraní.

V momente, keď máte už existujúce objednávky (vzniknuté pred sprístupnením API) vo vlastnom systéme a chcete zahájiť prácu s nimi cez API, použite funkciu „Zahájiť prácu s označenými objednávkami cez API“ v menu „Hromadné akcie s objednávkami“.

Popis obvyklých HTTP odpovedí

  • 200 OK – požiadavka bola úspešne spracovaná
  • 204 No Content – požiadavka bola úspešne spracovaná, odpoveď nemá žiadny obsah
  • 400 Bad Request – požiadavka nie je validná – môže sa jednať o chýbajúce alebo nevalidné parametre oproti špecifikácii
  • 403 Forbidden – autorizácia klienta zlyhala
  • 404 Not Found – koncový bod alebo požadované údaje neboli nájdené
  • 405 Method Not Allowed – koncový bod nepodporuje tento protokol HTTP metódu
  • 422 Unprocessable Entity – očakávaná chyba pri spracovaní požiadavky (pozri časť Chybové stavy )
  • 500 Internal Server Error – došlo k chybe na strane serveru
  • 502 Bad Gateway – došlo k chybe na strane serveru
  • 503 Service Unavailable – server je v maintenance móde (môže prebiehať deploy novej verzie, alebo plánovaná odstávka)
  • 504 Gateway Timeout – došlo k chybe na strane serveru

Odpovede HTTP 5×x nemusia používať formát JSON.

V prípade chýb 4xx je chyba v odchádzajúcej požiadavke a pred opakovaním pokusu je potrebné ju opraviť.

Chyby 5xx značia chyby serveru a požiadavku je možné opakovať bez jej zmeny. V prípade 503 by volajúcí mal rešpektovať hlavičku odpovede Retry-After a ďalší pokus opakovať až po uplynutí doby uvedenej v hlavičke.

Stavy objednávky

Objednávka je vždy v jednom z následujúcich stavov:

Hodnota stavu Popis
1 Nová zaplatená objednávka
2 Vybavuje sa
3 Na ceste (iba objednávky s dopravou)
4 Pripravuje sa k osobnému odberu – napr. prebieha preprava na pobočku
5 Pripravené k osobnému odberu
6 Doručené zákazníkovi – čaká na potvrdenie zákazníkom
7 Doručené a potvrdené zákazníkom
8 Zákazník odmietol potvrdiť prevzatie objednávky
9 Stornovaná objednávka

O každej zmene stavu je zákazník informovaný e‑mailom.

Objednávka nemusí nutne prejsť všetkými stavmi k úspešnému doručeniu, zo stavu „Nová zaplatená objednávka“ je možné prejsť rovno do „Na ceste“ / „Pripravené k osobnému odberu“ a potom do „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“. Využitie všetkých stavov však vedie k lepšej informovanosti zákazníka o priebehu vybavovania objednávky a doporučujeme ho.

Chybové stavy

V prípade HTTP kódov 4×x odpoveď vždy obsahuje kľúč status (viď. číselník nižšie) a pole messages s textovými popismi chýb.

Hodnota stavu Popis
1 Nevalidná požiadavka – chýbajúce alebo nevalidné hodnoty
2 Neplatné prihlasovacie údaje
3 Neexistujúca objednávka
4 Neexistujúca položka objednávky
5 Prechod objednávky do nepovoleného stavu
6 Neplatné storno – stornovanie väčšieho počtu položiek, než existuje
7 Iná chyba
8 Objednávka nebola ešte exportovaná do partnerského API – nie je možné s ňou skrz API manipulovať
9 Pre automatické nastavenie stavu „Tovar doručený zákazníkovi“ je potrebné zásielku nechať automaticky nastaviť do stavu „Tovar pripravený k vyzdvihnutiu“

Ukázka:

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

Dátové typy

Dátové typy jednotlivých kľúčov v požiadavkách a odpovediach sú vždy popísané u konkrétnych endpointov. Pokiaľ nie je uvedené inak, hodnota v úvodzovkách "" je vždy povinný string. Pokiaľ nie je uvedené inak, číselná hodnota je vždy povinný integer.

Komunikácia Zľavomat ⇒ Partner

Táto časť API je implementovaná na strane partnera a Zľavomat jej volá.

Požadovanú koreňovú URL API zdelí partner, mala by byť v tvare

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

Autorizácia požiadaviek

Pri zapnutí API partner obdrží partner_api_se­cret, ktorým sa prichádzajúce požiadavky preukazujú, že pochádzajú naozaj od Zľavomatu.

Tento parameter sa odovzdáva v HTTP hlavičce X-PartnerApiSecret.

Testovacie rozhranie

Zľavomat obsahuje funkcionalitu na prevolanie API na partnerskej strane a zobrazenie odpovede. Ku koreňovej URL uvedenej partnerom pri sprístupnení API je pripojené -test, takže v rámci testovania je prevolávané API na adrese např.

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

aby nedošlo k premiešaniu testovacích dát s ostrými objednávkami.

Testovanie partnerského API prebieha pomocou POST požiadaviek na nasledujúce adresy:

Časť URL <orderId> nahraďte za ľubovoľné číslo objednávky, s týmto číslom objednávky sú prevádzané požiadavky na partnerské API.

Požiadavky na toto testovacie rozhranie je potrebné autorizovať hlavičkami X-PartnerToken a X-ApiSecret.

Pri testovacom prevolávaní partnerského API systém posiela hlavičku X-PartnerApiSecret rovnako ako v ostrej prevádzke.

Dáta zasielané s novou objednávkou sú testovacieho charakteru a náhodne generované.

V prípade zasielania storna objednávky je potrebné v POST tele požiadavky uviesť v JSONu pole items (v rovnakom formáte ako zasiela API), ktoré testovacie rozhranie zvaliduje a partnerskému API prepošle v rovnakej podobe.

Nová objednávka

Požiadavka obsahuje dáta novo vytvorenej objednávky.

Objednávky majú vždy unikátne zlavomatId. Pokiaľ do API príde duplicitné zlavomatId, požiadavku by partnerské API malo ignorovať (prvú prevedenú požiadavku Zľavomat vyhodnotil ako neúspešnú a preto ju opakujeme) a odpovedať taktiež HTTP 204.

created je dátum vo formáte ISO 8601, teda YYYY-MM-DD'T'HH:mm:ss­+zz:zz.

productId obsahuje ID akcie, variantId ID zakúpeného variantu.

Nepovinné internalId značí interné ID zadávané pri variante akcie pri jej vytváraní v partnerskom rozhraní. Slúži k identifikáci produktu v systéme partnera.

V billingAddress (fakturačná adresa) je povinné iba meno (name) zákazníka.

V shippingAddress (doručovacia adresa) je nepovinná firma (company). V prípade doručenia na adresu shippingAddress obsahuje adresu zákazníka, v prípade osobného odberu adresu prevádzky, kde si zákazník tovar vyzdvihne.

Kľúč delivery.type môže nadobúdať hodnoty address (doručenie na adresu) alebo pickup (osobný odber). delivery.name obsahuje názov dopravy alebo meno prevádzky.

delivery.expec­tedShippingDa­te (predpokladaný dátum odoslania) a delivery.expec­tedDeliveryDa­te (predpokladaný dátum doručenia) sú dáta vo formáte YYYY-MM-DD.

Kľúč weight obsahuje hmotnosť objednávky v kilogramoch. V prípade, že nepoznáme hmotnosť všetkých položiek objednávky, nadobúda hodnotu null.

POST /order/$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 /order/$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á aktualizácia očakávaných dát odoslania

V prípade, že deals manažér na žiadosť partnera posunie hromadne dáta odeslania vybraných objednávok, systém informuje partnerské API o tejto aktualizácii.

Odosielané dáta obsahujú pole s ID objednávok a nový očakávaný dátum odoslania.

POST /update-shipping-dates
{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Storná

Storno je možné vytvoriť ako na strane Zľavomatu tak aj partnerského systému. Tento endpoint obsluhuje vytvorenie storna na strane Zlavomatu a jeho prenos do systému partnera.

Vytvorí storno položiek objednávky v určenom množstve. Pokiaľ má byť objednávka stornovaná celá, sú uvedené všetky položky so zodpovedajúcim množstvom.

Jednotlivé položky je možné stornovať aj čiastočne (napr. 1 kus z dvoch).

Poznámka k 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ě" }

Potvrdenie doručenia

Potom čo označíte objednávku ako „Doručené zákazníkovi“ si vyžiadame od zákazníka potvrdenie, že ju naozaj prevzal. Keď je objednávka označena ako prevzatá, dôjde k prevolaniu tohoto endpointu.

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

Odmietnutie prevzatia

POST /order/$slevo­matId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Zmena stavu objednávky na „Pripravené k osobnému odberu“

K prevolaniu tohoto endpointu dôjde v prípade, kedy bol predchádzajúci stav „Pripravuje sa k osobnému odberu“ nastavený s autoMarkRea­dyForPickuptrue a na strane Zľavomatu došlo k automatickému prepnutiu objednávky do stavu „Pripravené k osobnému odberu“

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

Zmena stavu objednávky na „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“

K prevolaniu tohoto endpointu dôjde v prípade, kedy bol predchádzajúci stav „Na ceste“, „Pripravuje sa k osobnému odberu“ nebo „Pripravené k osobnému odberu“ nastavený s autoMarkDeli­veredtrue a na strane Zľavomatu došlo k automatickému prepnutiu objednávky do stavu „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“.

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

Komunikácia Partner ⇒ Zľavomat

Tato část API je implementovaná na strane Zľavomat a volá jej partnerský systém.

Koreňová URL API je

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

PHP knihovna

Pro implementaci tejto strany API je možné využiť pripravenú PHP knižnicu. Kničnica aktuálne vyžaduje verziu PHP 5.4 alebo vyššiu a predpokladá využitie nástroja Composer.

Návod na použitie knižnice a zdrojové kódy sú na GitHubu.

Autorizácia požiadaviek

Pri zapnutí API partner obdrží partner_token a api_secret, ktorými sa preukazuje pri volaní API Zlavomatu.

Tieto parametre sú predávané v hlavičkách X-PartnerToken a X-ApiSecret.

Testovacie rozhranie

Koreňová URL testovacieho rozhranoa je

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

Je možné na ňom volať všetky akcie ako na ostatnom rozhraní.

Testovacie rozhranie kontroluje autorizáciu požiadaviek (správnosť partner tokenu a API secret) a validitu prichádzajúcich tiel požiadaviek (JSON). V týchto ohľadoch sa chová zhodne s ostrým API.

Testovacie rozhranie ovšem nepracuje so skutečnými objednávkami. Nevaliduje teda, či objednávka prechádza medzi správnymi stavmi a či obsahuje položky s danými ID. Akonáhle prejde autorizácia a validovanie formy požiadavky, testovacie rozhranie vždy odpovedá úspěšný kód 200 nebo 204.

Vytvorenie storna

Vytvorenie storno položiek objednávky v určenom množstve. Pokiaľ má byť objednávka stornovaná celá, sú uvedené všetky položky s odpoedajúcim množstvom.

Jednotlivé položky je možné stornovať aj čiastočne (napr. 1 kus z dvoch).

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

POST /order/$slevo­matId/cancel

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

Zmena stavu objednávky na „Vybavuje sa“

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

{}

Zmena stavu objednávky na „Na ceste“

Pri objednávke ide parametrom autoMarkDelivered určiť, či sa po nastavenej lehote dopravy („Doba od odoslania tovaru do doručenia“) má automaticky prepnúť do stavu „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“.

Odpoveď obsahuje aktualizovaný predpokladaný dátum doručenia.

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

{ "autoMarkDeli­vered": true }

Response 200

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

Zmena stavu objednávky na „Pripravuje sa k osobnému odberu“

Pri objednávke ide parametrom autoMarkReady­ForPickup určiť, či sa po uplynutí doby od odoslania tovaru do doručenia pri danom type odberového miesta má automaticky prepnúť do stavu „Pripravené k osobnému odberu“.

Pri objednávke ide parametrom autoMarkDelivered určiť, či sa po nastavenej lehote počtu dní na vyzdvihnutie pri danom type odberového miesta má automaticky prepnúť zo stavu „Pripravené k osobnému odberu“ do stavu „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“.

Kombinácia parametrov autoMarkReady­ForPickup false a autoMarkDelivered true nie je povolená. V takom prípade sa vráti chybový kód 9.

Odpoveď obsahuje aktualizovaný predpokladaný dátum doručenia.

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

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

Response 200

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

Zmena stavu objednávky na „Pripravené k osobnému odberu“

Pri objednávke ide parametrom autoMarkDelivered určiť, či sa po nastavenej lehote počtu dní na vyzdvihnutie pri danom type odberového miesta má automaticky prepnúť do stavu „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“.

POST /order/$slevo­matId/mark-ready-for-pickup
{ "autoMarkDeli­vered": true }

Zmena stavu objednávky na „Doručené zákazníkovi – čaká na potvrdenie zákazníkom“

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

Zmena doručovacej adresy

Doručovaciu adresu je možné meniť iba pri doručení na adresu (t.j. miesto odobného odberu meniť nejde).

Všetky kľúče okrem company sú povinné.

Validné hodnoty pre kľúč state sú 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" }
Späť na výpis článkov

Súvisiace články
Nahoru