API tretej strany

API slúži na prenos informácií o objednávkach medzi Slevomatom a systémom nášho obchodného partnera. API vyžaduje implementáciu obojsmernej komunikácie – systém Slevomat volá API partnera a partner volá API Slevomatu.

Objednávky exportované do partnerského API už nie je možné v partnerskom rozhraní Slevomatu manipulovať, iba prezerať. Manipulácia s exportovanými objednávkami môže prebiehať len cez API.

Všetky požiadavky musia byť uskutočnené na HTTPS a všetky údaje sú vo formáte JSON.

API prístup

Prístup k povereniam API získate na karte Nastavenia v rozhraní partnera. Na získanie údajov je potrebné poskytnúť koreňovú URL partnerskej časti API pre použitie v smere Slevomat → Partner, napr.

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

Prístupové údaje sa zobrazia iba raz, keď pristúpite k API, starostlivo si ich uložte.

Po pristúpení k API systém do neho začne exportovať novovytvorené objednávky.

Počiatočný export údajov

Na prenos existujúcich objednávok v momente prístupu k API môžete využiť jednorazový export do CSV v partnerskom rozhraní.

Ak máte existujúce objednávky (vytvorené pred sprístupnením API) vo vlastnom systéme a chcete s nimi začať pracovať cez API, použite funkciu „Začať pracovať s označenými objednávkami cez API“ v časti „Hromadné akcie s objednávkami“ Ponuka.

Popis bežných odpovedí HTTP

• 200 OK – žiadosť bola úspešne spracovaná
• 204 No Content – požiadavka bola spracovaná, odpoveď nemá obsah
• 400 Bad Request – požiadavka je neplatná – môžu chýbať alebo neplatné parametre oproti špecifikácii
• 403 Forbidden – autorizácia klienta zlyhala
• 404 Not Found – koncový bod alebo požadované údaje sa nenašli
• 405 Method Not Allowed – koncový bod nepodporuje túto metódu HTTP
• 422 Unprocessable Entity – očakávaná chyba počas spracovania požiadavky (pozri časť Chybové stavy )
• 500 Internal Server Error – vyskytla sa chyba na strane servera
• 502 Bad Gateway – vyskytla sa chyba na strane servera
• 503 Service Unavailable – server je v režime údržby (môže prebiehať nasadzovanie novej verzie alebo môže byť plánovaný výpadok)
• 504 Gateway Timeout – vyskytla sa chyba na strane servera

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

V prípade4xx chyby, odchádzajúca požiadavka je chybná a pred opätovným pokusom ju treba opraviť.

Chyby5xx indikujú chyby servera a požiadavku možno zopakovať bez zmeny. V prípade503 , volajúci by mal rešpektovaťRetry-After hlavičku odpovede a skúste to znova až po uplynutí času uvedeného v hlavičke.

Stavy objednávok

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

O každej zmene stavu je zákazník informovaný emailom.

Objednávka nemusí pre úspešné doručenie prejsť všetkými stavmi, z "Nová objednávka zaplatená" je možné prejsť rovno na "Tovar odoslaný" / "Pripravený k osobnému odberu" a následne na "Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom" ". Používanie všetkých stavov však vedie k lepšej informovanosti zákazníka o priebehu objednávky a je odporúčané.

Chybové stavy

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

Príklad:

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

Typy údajov

Typy údajov každého kľúča v požiadavkách a odpovediach sú vždy opísané pre konkrétne koncové body. Ak nie je uvedené inak, hodnota v úvodzovkách"" je vždy povinný reťazec. Ak nie je uvedené inak, číselná hodnota je vždy povinné celé číslo.

Komunikácia Slevomat ⇒ Partner

Táto časť API je implementovaná na strane partnera a volá ju Slevomat.

Požadovanú koreňovú adresu URL rozhrania API poskytuje partner a mala by byť vo formulári

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

Požiadať o autorizáciu

Keď je rozhranie API povolené, partner dostanepartner_api_se­cret , čo dokazuje, že prichádzajúce požiadavky sú skutočne zo Slevomatu.

Tento parameter sa odovzdáva v hlavičke HTTPX-PartnerApiSecret .

Testovacie rozhranie

Slevomat obsahuje funkcionalitu na volanie API na strane partnera a zobrazenie odpovede. Koreňová adresa URL zadaná partnerom pri sprístupnení rozhrania API je pripojená-test , takže pri testovaní sa API volá napr

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

aby sa predišlo zmiešaniu testovacích údajov s aktuálnymi objednávkami.

Testovanie partnerského API sa vykonáva prostredníctvom požiadaviek POST na nasledujúce 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á aktualizácia očakávaných dátumov odoslania

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

   – Zmeňte stav objednávky na „Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom“

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

   – Zmeňte stav objednávky na "Pripravené na osobný odber"

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

   – Potvrdenie o doručení

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

   – Odmietnutie prijatia

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

   – Zrušenie

Vymeňte<orderId> časť URL s ľubovoľným číslom objednávky, požiadavky na partnerské API sa uskutočňujú s týmto číslom objednávky.

Požiadavky na toto testovacie rozhranie musia byť autorizované hlavičkamiX-PartnerToken aX-ApiSecret .

Keď vykonáte testovacie volanie do partnerského API, systém odošleX-PartnerApiSecret hlavičky ako je to v ostrej prevádzke.

Údaje odoslané s novou objednávkou sú testovacie údaje a sú náhodne generované.

V prípade odoslania zrušenia objednávky je potrebné uviesťitems pole v tele POST požiadavky vo formáte JSON (v rovnakom formáte, aký odosiela API), ktoré testovacie rozhranie overí a odošle partnerskému API v rovnakej forme.

Nová objednávka

Žiadosť obsahuje údaje novovytvorenej objednávky.

Objednávky majú vždy unikátslevomatId . Ak API dostane duplikátslevomatId , požiadavka by mala byť partnerským API ignorovaná (prvá požiadavka bola Slevomatom vyhodnotená ako neúspešná a teda opakovaná) a odpoveď by mala byť tiežHTTP 204 .

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

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

VoliteľnéinternalId označuje interné ID zadané pre variant akcie pri jeho vytváraní v partnerskom rozhraní. Slúži na identifikáciu produktu v systéme partnera.

InbillingAddress (fakturačná adresa) iba meno zákazníka (name ) Je povinné.

InshippingAddress (adresa doručenia) spoločnosť (company ) je voliteľný. V prípade doručenia doshippingAddress 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 mať hodnotuaddress (doručenie na adresu) príppickup (osobný odber).delivery .name obsahuje názov prepravy alebo názov prevádzkarne.

delivery .expec­tedShippingDa­te (odhadovaný dátum odoslania) adelivery .expec­tedDeliveryDa­te (predpokladaný dátum dodania) sú údaje vo formáteYYYY-MM-DD .

Kľúčweight obsahuje hmotnosť objednávky v kilogramoch. Ak nepoznáme váhu všetkých položiek v objednávke, preberá túto hodnotunull .

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

Ak manažér obchodov na žiadosť partnera posunie dátumy odoslania vybraných objednávok, systém o tejto aktualizácii informuje partnerské API.

Odoslané údaje obsahujú pole ID objednávky a nový predpokladaný dátum odoslania.

POST /update-shipping-dates

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

Zrušenie

Storno je možné vytvárať na strane Slevomatu aj na partnerskom systéme. Tento koncový bod rieši vytvorenie storna na strane Slevomatu a jeho prenos do systému partnera.

Vytvára storno položiek objednávky v zadanom množstve. Ak sa má zrušiť celá objednávka, sú uvedené všetky položky s príslušným množstvom.

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

Poznámka o zrušení (note ) je voliteľný.

POST /order/$slevo­matId/cancel

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

Potvrdenie o doručení

Po označení objednávky ako „Doručená zákazníkovi“ požiadame zákazníka o potvrdenie, že ju skutočne prijal. Keď je objednávka označená ako prijatá, zavolá sa tento koncový bod.

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

{}

Odmietnutie prijatia

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

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

Zmeniť stav objednávky na „Pripravené na osobný odber“

Tento koncový bod sa zavolá, ak bol nastavený predchádzajúci stav „Pripravené na osobné vyzdvihnutie“.autoMarkRea­dyForPickuptrue a objednávka bola automaticky prepnutá na "Pripravené k osobnému odberu" na strane Slevomatu.

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

{}

Zmeňte stav objednávky na „Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom“

Tento koncový bod sa nazýva, ak bol predchádzajúci stav „Na ceste“, „Pripravený na osobný odber“ alebo „Pripravený na osobný odber“ nastavený sautoMarkDeli­veredtrue a objednávka bola na strane Slevomatu automaticky prepnutá do stavu „Doručená zákazníkovi – čaká na potvrdenie zákazníkom“.

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

{}

Komunikačný partner ⇒ Slevomat

Táto časť API je implementovaná na strane Slevomatu a je volaná partnerským systémom.

Koreňová adresa URL rozhrania API je

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

PHP knižnica

Na implementáciu tejto strany API môžete použiť pripravenú PHP knižnicu. Knižnica v súčasnosti vyžaduje PHP 5.4 alebo vyšší a vyžaduje použitie Composer.

Návod na používanie knižnice a zdrojového kódu je na GitHub .

Požiadať o autorizáciu

Keď je rozhranie API povolené, partner dostanepartner_token aapi_secret , ktoré slúžia na ich autentifikáciu pri volaní Slevomat API.

Tieto parametre sa odovzdávajú vX-PartnerToken aX-ApiSecret hlavičky.

Testovacie rozhranie

Koreňová adresa URL testovacieho rozhrania je

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

Všetky akcie sa na ňom dajú vyvolať ako na živom rozhraní.

Testovacie rozhranie kontroluje autorizáciu požiadaviek (správnosť tokenu partnera a tajomstva API) a platnosť tiel prichádzajúcich požiadaviek (JSON). V týchto ohľadoch sa správa identicky ako živé API.

Testovacie rozhranie však nefunguje so skutočnými objednávkami. Neoveruje teda, či objednávka prechádza medzi správnymi stavmi a či obsahuje položky s danými ID. Po úspešnom overení autorizácie a formulára žiadosti sa testovacie rozhranie vždy zhoduje s kódom úspechu 200 alebo 204.

Vytvorenie zrušenia

Vytvorí zrušenie položiek objednávky v zadanom množstve. Ak má byť objednávka zrušená celá, sú uvedené všetky položky s príslušným množstvom.

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

Poznámka o zrušení (note ) je voliteľný.

POST /objednávka/$slevomatId/zrušiť

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

Zmeniť stav objednávky na „Čaká“

POST /order/$slevomatId/mark-pending

{}

Zmeniť stav objednávky na „Tovar odoslaný“

Pre objednávku, autoMarkDelivered parameter možno použiť na určenie, či sa má automaticky prepnúť do stavu "Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom" po nastavenom čase odoslania ("Čas od odoslania po doručenie").

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

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

{ "autoMarkDeli­vered": true }

Odpoveď 200

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

Zmeniť stav objednávky na „Pripravené na osobný odber“

Môžete použiť parameterautoMarkReady­ForPickup určiť, či sa má objednávka po čase od odoslania po doručenie pre daný typ odberného miesta automaticky prepnúť do stavu „Pripravená na osobný odber“.

Pre objednávku, autoMarkDelivered parametrom možno určiť, či sa má po nastavenom počte dní na vyzdvihnutie na danom type odberného miesta automaticky prepnúť zo stavu „Pripravené na osobný odber“ do stavu „Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom“.

Kombinácia parametrovautoMarkReady­ForPickup falošné aautoMarkDelivered pravda nie je povolená. V tomto prípade sa vráti chybový kód 9.

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

POST /order/$slevomatId/mark-getting-ready-for-pickup

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

Odpoveď 200

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

Zmeniť stav objednávky na „Pripravené na osobný odber“

TheautoMarkDelivered parametrom možno určiť, či sa má objednávka po nastavenom počte dní na vyzdvihnutie na danom type odberného miesta automaticky prepnúť do stavu „Doručená zákazníkovi – čaká sa na potvrdenie zákazníkom“.

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

{ "autoMarkDeli­vered": true }

Zmeňte stav objednávky na „Doručené zákazníkovi – čaká sa na potvrdenie zákazníkom“

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

{}

Zmeniť adresu doručenia

Doručovaciu adresu je možné zmeniť len pre doručovanie na adresu (tzn. nemožno zmeniť miesto osobného odberu).

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

Platné hodnoty prestate kľúčové súcz (Č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" }

Denník zmien