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

API tretej strany

Tento článok bol strojovo preložený.

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

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

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

Prístup k API

Prístup k povereniam API môžete získať na karte Nastavenia v partnerskom rozhraní. Pre získanie údajov je potrebné zadať koreňovú URL adresu partnerskej časti API pre použitie v smere Slevomat → Partner, napr. 

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

Prístupové údaje sa pri prístupe k API zobrazia len raz, starostlivo si ich uložte.

Po získaní prístupu k rozhraniu API doň systém začne exportovať novovytvorené objednávky.

Počiatočný export údajov

Ak chcete preniesť existujúce objednávky v okamihu prístupu k API, môžete použ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 ponuke „Hromadné akcie s objednávkami“.

Popis bežných odpovedí HTTP

  • 200 OK – požiadavka bola úspešne spracovaná
  • 204 No Content – žiadosť bola spracovaná, odpoveď nemá žiadny obsah
  • 400 Bad Request – požiadavka nie je platná – môžu chýbať alebo byť neplatné 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 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 – na strane servera došlo k chybe
  • 502 Bad Gateway – došlo k chybe na strane servera
  • 503 Service Unavailable – server je v režime údržby (môže prebiehať nasadenie novej verzie alebo plánovaná odstávka)
  • 504 Gateway Timeout – došlo k chybe na strane servera

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

V prípade chýb 4xx je chyba na strane odchádzajúcej požiadavky a pred opakovaním pokusu ju treba opraviť.

Chyby 5xx označujú chyby servera a požiadavku možno opakovať bez jej zmeny. V prípade 503, by mal volajúci rešpektovať hlavičku odpovede Retry-After a opakovať pokus až po uplynutí času uvedeného v hlavičke.

Stavy objednávok

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

Hodnota stavu Popis
1 Nová platená objednávka
2  Spracované
3  Na ceste (len objednávky s dopravou)
4  Príprava na osobný odber – napr. preprava na pobočku
5  Pripravené na osobný odber
6  Dodané zákazníkovi – čaká sa na potvrdenie zákazníka
7  Dodané a potvrdené zákazníkom
8  Zákazník odmietol potvrdiť prijatie objednávky
9  Zrušená objednávka

Zákazník je informovaný o akejkoľvek zmene stavu e‑mailom.

Objednávka nemusí nevyhnutne prejsť všetkými stavmi pre úspešné doručenie, z „Nová objednávka zaplatená“ je možné prejsť rovno do stavu „Na ceste“ / „Pripravené na osobný odber“ a potom do stavu „Doručené zákazníkovi – čaká sa na potvrdenie zákazníka“. Používanie všetkých stavov však vedie k lepšej informovanosti zákazníka o priebehu objednávky a odporúča sa.

Chybové stavy

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

Hodnota stavu Popis
1  Neplatná požiadavka – chýbajúce alebo neplatné hodnoty
2  Neplatné prihlasovacie údaje
3  Neexistujúce poradie
4  Neexistujúca položka objednávky
5  Prechod zákazky do nepovoleného stavu
6  Neplatné zrušenie – zrušenie viac položiek, ako existuje
7  Iná chyba
8  Objednávka ešte nebola exportovaná do partnerského API – nie je možné s ňou manipulovať prostredníctvom API
9  Ak chcete automaticky nastaviť stav „Tovar doručený zákazníkovi“, musíte mať zásielku automaticky nastavenú na „Tovar pripravený na vyzdvihnutie“.

Príklad: 

{ "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é 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 Slevomat ju volá.

Požadovanú koreňovú URL adresu API poskytuje partner a mala by byť v tvare 

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

Autorizácia požiadavky

Keď je API povolené, partner dostane adresu partner_api_se­cret, ktorá dokazuje, že prichádzajúce požiadavky sú skutočne zo Slevomatu.

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

Testovacie rozhranie

Slevomat obsahuje funkciu na volanie API na strane partnera a zobrazenie odpovede. K adrese -test je pripojená koreňová adresa URL, ktorú partner zadal pri sprístupnení API, takže pri testovaní sa API volá napr. 

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

aby sa zabránilo miešaniu testovacích údajov s reálnymi objednávkami.

Testovanie partnerského API sa vykonáva prostredníctvom POST požiadaviek 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
    - Zmena stavu objednávky na „Dodané zákazníkovi – čaká sa na potvrdenie zákazníka“ 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup
    - Zmena stavu 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

Nahraďte časť adresy URL <orderId> ľubovoľným číslom objednávky, požiadavky na partnerské rozhranie API sa uskutočnia s týmto číslom objednávky.

Požiadavky na toto testovacie rozhranie musia byť autorizované pomocou hlavičiek X-PartnerToken a X-ApiSecret.

Pri testovacom volaní na partnerské rozhranie API systém posiela hlavičku X-PartnerApiSecret rovnako ako v reálnej 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é do tela POST požiadavky v tvare JSON (v rovnakom formáte, v akom ho odosiela API) zahrnúť pole items, ktoré testovacie rozhranie overí a v rovnakom tvare prepošle partnerskému API.

Nová objednávka

Požiadavka obsahuje údaje o novo vytvorenej objednávke.

Objednávky majú vždy jedinečný slevomatId. Ak API dostane duplicitnú požiadavku slevomatId, partnerské API by ju malo ignorovať (prvá požiadavka bola Slevomatom vyhodnotená ako neúspešná, a preto sa opakovala) a odpoveď by mala byť tiež HTTP 204.

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

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

Nepovinný údaj internalId uvádza interné ID zadané pre variant akcie pri jeho vytvorení v partnerskom rozhraní. Používa sa na identifikáciu produktu v systéme partnera.

V položke billingAddress (fakturačná adresa) je povinný len názov zákazníka (name).

V položke shippingAddress (adresa dodania) je spoločnosť (company) nepovinná. V prípade doručenia na shippingAddress obsahuje adresu zákazníka, v prípade osobného odberu adresu prevádzkarne, kde si zákazník tovar vyzdvihne.

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

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

Kľúč weight obsahuje hmotnosť objednávky v kilogramoch. Ak nepoznáme hmotnosť všetkých položiek v objednávke, nadobúda 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á aktualizácia očakávaných dátumov odoslania

Ak správca obchodov na žiadosť partnera hromadne presunie 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ý očakávaný dátum odoslania. 

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

Zrušenie objednávky

Storno je možné vytvoriť na strane Slevomatu aj v partnerskom systéme. Tento koncový bod spracováva 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á stornovať celá objednávka, uvedú sa všetky položky s príslušným množstvom.

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

Poznámka o zrušení (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 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 dostal. 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" }

Zmena stavu objednávky na „Pripravené na osobný odber“

Tento koncový bod sa zavolá, ak bol na previous nastavený stav „Pripravené na osobný odber“ pomocou autoMarkRea­dyForPickuptrue a objednávka bola na strane Slevomatu automaticky prepnutá na „Pripravené na osobný odber“. 

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

Zmena stavu objednávky na „Doručená zákazníkovi – čaká sa na potvrdenie zákazníka“.

Tento koncový bod sa volá v prípade, ak bol na stránke previous nastavený stav „Na ceste“, „Pripravené na osobný odber“ alebo „Pripravené na osobný odber“ pomocou autoMarkDeli­veredtrue a objednávka bola na strane Slevomatu automaticky prepnutá do stavu „Doručené zákazníkovi – čaká sa na potvrdenie zákazníka“. 

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á URL adresa API je 

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

Knižnica PHP

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

Pokyny na používanie knižnice a zdrojový kód nájdete na GitHub.

Autorizácia žiadosti

Keď je API povolené, partner dostane adresy partner_token a api_secret, ktoré sa používajú na autentifikáciu pri volaní Slevomat API.

Tieto parametre sa odovzdávajú v hlavičkách X-PartnerToken a X-ApiSecret.

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ť rovnako ako na živom rozhraní.

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

Testovacie rozhranie však nepracuje 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šnej autorizácii a overení formulára požiadavky sa testovacie rozhranie vždy zhoduje s kódom úspešnosti 200 alebo 204. 

Vytvorenie zrušenia

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

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

Poznámka o zrušení (note) je nepovinná.

POST /order/$slevomatId/cancel 

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

Zmena stavu objednávky na „Čaká na vybavenie“

POST /order/$slevomatId/mark-pending 

{}

Zmena stavu objednávky na „Na ceste“

Pre objednávku je možné pomocou parametra autoMarkDelivered určiť, či sa má po uplynutí nastaveného času prepravy („Čas od odoslania do doručenia“) automaticky prepnúť do stavu „Dodané zákazníkovi – čaká sa na potvrdenie zákazníka“.

Odpoveď obsahuje aktualizovaný odhadovaný dátum dodania.

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

{ "autoMarkDeli­vered": true }

Odpoveď 200 

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

Zmena stavu objednávky na „Pripravené na osobný odber“

Pomocou parametra autoMarkReady­ForPickup môžete určiť, či sa má objednávka automaticky prepnúť do stavu „Pripravená na osobný odber“ po uplynutí času od odoslania do doručenia pre daný typ odberného miesta.

Pre objednávku môžete pomocou parametra autoMarkDelivered určiť, či sa má automaticky prepnúť zo stavu „Pripravené na osobný odber“ do stavu „Dodané zákazníkovi – čaká sa na potvrdenie zákazníka“ po stanovenom počte dní na odber v danom type odberného miesta.

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

Odpoveď obsahuje aktualizovaný očakávaný 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" }

Zmena stavu objednávky na „Pripravená na osobný odber“

Parameter autoMarkDelivered možno použiť na určenie, či sa má objednávka po stanovenom počte dní pre odber na danom type odberného miesta automaticky zmeniť na stav „Dodané zákazníkovi – čaká sa na potvrdenie zákazníka“. 

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

Zmena stavu objednávky na „Dodané zákazníkovi – čaká na potvrdenie zákazníka“ 

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

Zmena adresy dodania

Doručovaciu adresu je možné zmeniť len v prípade doručenia na adresu (t. j. nie je možné zmeniť miesto osobného odberu).

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

Platné 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" }

Zoznam zmien

Späť na výpis článkov

Súvisiace články
Nahoru