Zboží třetí strany API

Rozhraní API se používá k přenosu informací o objednávkách mezi službami Discountomat a systémem obchodního partnera. Rozhraní API vyžaduje implementaci oboustranného komunikace – systém Discountomat volá API partnera a partner volá API. Diskontní systém.

U objednávek exportovaných do partnerského API již není možné s nimi manipulovat v rozhraní partnera, lze je pouze prohlížet. Manipulaci s exportovanými objednávkami lze provádět pouze prostřednictvím API.

Všechny požadavky musí být provedeny na protokolu HTTPS a všechna data jsou ve formátu JSON formátu.

Přístupnost API

Přístup k rozhraní API můžete získat na kartě Nastavení v aplikaci Partnerského rozhraní. Chcete-li získat data, musíte zadat kořenový kód URL partnerské části API pro použití ve směru Zlevomat → Partner, např.

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

Přístupové údaje se zobrazí pouze při přístupu k API, pozorně si je přečtěte pečlivě si je uschovejte.

Jakmile je API zpřístupněno, nově vytvořené objednávky jsou do něj zadávány systémem začne exportovat objednávky do systému.

Počáteční export dat

Přetečení existujících objednávek v okamžiku zpřístupnění API Lze použít jednorázový export do CSV v partnerském rozhraní.

V okamžiku, kdy máte existující objednávky (vytvořené před zpřístupněním API) ve vlastním systému a chcete s nimi začít pracovat prostřednictvím 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 odpovědí HTTP

• 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ý – může mohou chybět nebo být neplatné parametry oproti specifikaci
• 403 Forbidden – autorizace klienta selhala
• 404 Not Found – požadovaný koncový bod nebo data nebyly nalezeny
• 405 Method Not Allowed – koncový bod to nepodporuje metodu protokolu HTTP
• 422 Unprocessable Entity – očekávaná chyba na zpracování požadavku (viz část Chybové stavy )
• 500 Internal Server Error – na stránce došlo k chybě server
• 502 Bad Gateway – došlo k chybě na straně serveru
• 503 Service Unavailable – server je v režimu údržby (může probíhat nasazení nové verze nebo plánovaná odstávka)
• 504 Gateway Timeout – na straně serveru došlo k chybě server

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

V případě chyby 4xx je chyba v odchozím požadavku a je třeba ji před opakováním pokusu opravit.

Chyby 5xx označují chyby serveru a požadavek může být být opakován, aniž by se změnil. V případě chyby 503, by měl volající respektovat hlavičku odpovědi Retry-After a další pokus opakovat až po uplynutí doby uvedené v záhlaví.

Stavy objednávek

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

Hodnota stavu	Popis
1	Nová zaplacená objednávka
2	Zpracovává se
3	Na cestě (pouze objednávky s dopravou)
4	V přípravě k osobnímu odběru – např. při přepravě do pobočka
5	Připraveno k osobnímu odběru
6	Doručeno zákazníkovi – čeká se na potvrzení zákazníka
7	Dodáno a potvrzeno zákazníkem
8	Zákazník odmítl potvrdit přijetí objednávky
9	Objednávka zrušena

Zákazník je o změně stavu informován e‑mailem.

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

Chybové stavy

V případě 4×x kódů HTTP obsahuje odpověď vždy klíčový údaj status (viz seznam kódů níže) a pole messages s textovým popisem chyb.

Hodnota stavu	Popis
1	Neplatný požadavek – chybějící nebo neplatné hodnoty
2	Neplatné pověření
3	Neexistující objednávka
4	Neexistující položka objednávky
5	Přechod zakázky do neschváleného stavu
6	Neplatné zrušení – zrušení více položek než existuje
7	Jiná chyba
8	Objednávka ještě nebyla exportována do partnerského rozhraní API – není. nelze s ní manipulovat prostřednictvím API
9	Automatické nastavení stavu „Zboží dodáno zákazníkovi“ je nutné, aby zásilka byla automaticky nastavena do stavu „Zboží připraveno k odeslání“. připraveno k vyzvednutí“

Příklad:

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

Datové typy

Datové typy jednotlivých klíčů v požadavcích a odpovědích jsou následující jsou vždy popsány pro konkrétní koncové body. Pokud není uvedeno jinak, hodnota v uvozovkách "" je vždy povinný řetězec. Pokud není uvedeno jinak, je číselná hodnota vždy povinně celé číslo.

Komunikační diskontomat ⇒ Partner

Tato část API je implementována na straně partnera a používá ji Zlevomat volání.

Požadovaná kořenová adresa API je sdílena partnerem, měla by být ve tvaru

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

Autorizace požadavku

Pokud je API povoleno, partner obdrží adresu partner_api_se­cret, která se nachází na adrese příchozí požadavky jsou ověřovány, že skutečně přicházejí z Sleva.

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

Testovací rozhraní

Discountomat obsahuje funkce pro volání rozhraní API na straně partnera a zobrazit odpověď. Na kořenovou adresu URL zadanou partnerem při přístupu k rozhraní API. -test je připojena adresa URL partnera , takže při testování je volána. API na adrese např.

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

Aby nedošlo k promíchání testovacích dat s živými objednávkami.

Testování partnerského rozhraní API se provádí pomocí požadavků POST na adresu 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 „Dodáno zákazníkovi – čeká se na“. potvrzení od zákazníka“

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

   – Změnit stav objednávky na „Připraveno k osobnímu odběru“.

• 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šení

Nahraďte část adresy URL <orderId> libovolným číslem. číslo objednávky, s tímto číslem objednávky jsou žádosti předávány do API partnera.

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

Při testovacím volání na partnerské rozhraní API systém odešle hlavičku X-PartnerApiSecret hlavičku stejně jako v ostrém provozu.

Data odeslaná s novou objednávkou jsou testovací data a náhodně generovaná.

V případě odeslání zrušení objednávky je tělo POST. požadavku obsahovat v poli JSON items (ve stejném formátu jako v případě odeslaný rozhraním API), které bude ověřeno testovacím rozhraním a odesláno partnerskému rozhraní API. API jej předá ve stejném formátu.

Nová objednávka

Požadavek obsahuje údaje nově vytvořené objednávky.

Objednávky mají vždy jedinečné zlavomatId. Pokud API přijde duplikát zlavomatId, měl by být požadavek ignorovat (první převedený požadavek byl Discountomatem vyhodnocen jako neúspěšný a proto jej opakujeme) a odpovědět rovněž protokolem HTTP 204.

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

productId obsahuje ID události, variantId ID. zakoupené varianty.

Nepovinný údaj internalId označuje interní ID zadané při variantě 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 název. (name) zákazníka.

V shippingAddress (dodací adresa) je firma nepovinná. (company). V případě dodání na adresu shippingAddress je uvedena adresa zákazníka, v případě osobní doručení adresu provozovny, kde si zákazník zboží vyzvedne.

Klíč delivery.type může nabývat hodnot address (doručení na adresu) nebo pickup (osobní doručení). vyzvednutí). delivery.name obsahuje název přepravní nebo jiné název operace.

delivery.expec­tedShippingDa­te (očekávaný datum odeslání) a delivery.expec­tedDeliveryDa­te (předpokládané datum doručení) jsou údaje 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á hodnoty 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á aktualizace očekávaných dat odeslání

Pokud správce obchodů na žádost partnera odesílá hromadná data. data odeslání pro vybrané objednávky, systém o tom informuje rozhraní API partnera. aktualizaci.

Odeslaná data obsahují pole ID objednávky a nové očekávané datum odeslání.

POST /update-shipping-dates

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

Zrušení objednávky

Storna lze vytvářet jak na straně slevy, tak na straně partnera systému. Tento koncový bod zpracovává vytváření storen na straně Zlavomat a jeho přenos do systému partnera.

Vytváří storno položek objednávky v zadaném množství. Pokud je stornována celá objednávka, jsou všechny položky vypsány s odpovídajícím množstvím.

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

Poznámka o zrušení objednávky (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í o dodání

Poté, co označíte objednávku jako „Dodáno zákazníkovi“, můžete od zákazníka vyžádáme potvrzení, že ji skutečně obdržel. Když je objednávka označena jako doručená, bude zavolán tento koncový bod.

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

Tento koncový bod bude zavolán v případě, že na adrese previous. byl nastaven stav „Připraveno k osobnímu odběru“ pomocí autoMarkRea­dyForPickuptrue a na stránce Sleva byla objednávka automaticky přepnuta do stavu „Připraveno k odběru“. k osobnímu odběru“

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

{}

Změňte stav objednávky na „Doručeno zákazníkovi – čeká se na potvrzení zákazníka“

Tento koncový bod bude zavolán, pokud previous stav „Na cestě“, „Připraveno k osobnímu odběru“ nebo „Připraveno k vyzvednutí“. k osobnímu odběru“ byl nastaven pomocí autoMarkDeli­veredtrue a na stránce Sleva byla objednávka automaticky přepnuta do stavu „Doručeno“. zákazníkovi – čeká se na potvrzení zákazníka“.

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

{}

Komunikační partner ⇒ Zľavomat

Tato část API je implementována na straně Slevomatu a volá jej Partnerský systém.

Kořenová adresa URL rozhraní API je

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

Knihovna PHP

Pro implementaci této části API je možné použít připravené PHP knihovnu. Knihovna v současné době vyžaduje PHP verze 5.4 nebo vyšší a předpokládá použití nástroje Composer.

Návod k použití knihovny a zdrojový kód naleznete na serveru GitHub.

Autorizační požadavky

Když je rozhraní API povoleno, partner obdrží na stránky partner_token a api_secret , které slouží k ověření volání Zlavomat API.

Tyto parametry jsou předávány v hlavičkách X-PartnerToken a . X-ApiSecret .

Testovací rozhraní

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

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

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

Testovací rozhraní kontroluje autorizaci požadavků (správnost tokenu partnera a tajemství API) a platnost těl příchozích požadavků. (JSON). V těchto ohledech se chová identicky jako ostré rozhraní API.

Testovací rozhraní však nepracuje se skutečnými objednávkami. Neověřuje tedy, zda objednávka přechází mezi správnými stavy a zda obsahuje položky s danými ID. Jakmile projde autorizace a validace formy požadavku, testovací rozhraní vždy odpoví úspěšným kódem 200 nebo 204.

Vytvoření storna

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

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

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

POST /order/$slevomatId/cancel

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

Změna stavu objednávky na „V procesu“

POST /order/$slevomatId/mark-pending

{}

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

Při zadávání objednávky se parametr autoMarkDelivered používá k určení, zda je objednávka po uplynutí nastavené dodací lhůty („Doba od odeslání do dodání“) má být automaticky přejít do stavu „Dodáno zákazníkovi – čeká na doručení“. potvrzení zákazníka“.

Odpověď obsahuje aktualizované předpokládané datum dodání.

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

{ "autoMarkDeli­vered": true }

Odpověď 200

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

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

Když objednávka prochází přes autoMarkReady­ForPickup parametr zadat, zda je doba od odeslání do doručení pro daný typ odběrného místa má být automaticky změněn na stav „Připraveno k osobnímu odběru“. pro osobní odběr“.

Při objednávání se pomocí parametru autoMarkDelivered určuje, zda má být např. po uplynutí nastaveného počtu dnů pro vyzvednutí pro daný typ odběrného místa sběrného místa má být automaticky přepnuto 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í přípustná. V tomto případě je vrácen chybový kód 9.

Odpověď obsahuje aktualizované předpokládané datum dodání.

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

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

Odpověď 200

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

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

Při zadávání objednávky se pomocí parametru autoMarkDelivered určuje, zda je objednávka po uplynutí nastaveného počtu dnů pro vyzvednutí pro daný typ vyzvednutí odběrného místa má automaticky přejít do stavu „Dodáno zákazníkovi -“. čeká na potvrzení zákazníka“.

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

{ "autoMarkDeli­vered": true }

Změňte stav objednávky na „Dodáno zákazníkovi – čeká na potvrzení“. potvrzení zákazníka“

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

{}

Změna adresy pro doručení

Dodací adresu lze změnit pouze při doručení na adresu (tj. Nelze změnit místo vyzvednutí).

Všechny klíče kromě company jsou povinné.

Platné hodnoty pro klíč state jsou cz (český jazyk). 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" }