Slevomat.cz Partner API

API służy do przesyłania informacji o voucherach między Zlavomat a systemem partnera biznesowego. Umożliwia partnerowi weryfikację ważności voucherów w swoim systemie i ich realizację. Partner nie musi w tym celu korzystać z Interfejsu Partnera.

Możliwe przykłady wykorzystania:

• Klient dokonuje zakupu vouchera, którego warunkiem świadczenia usługi jest podanie kodu na stronie partnera podczas składania zamówienia. Dzięki API, po wpisaniu kodu, ważność vouchera jest natychmiast sprawdzana. Jego wartość jest następnie odejmowana z koszyka partnera, a voucher jest automatycznie realizowany w sklepie Zlavomot.
• W ten sam sposób ważność voucherów można sprawdzić w systemie rezerwacyjnym partnera lub klient może dokonać zakupu kredytu o określonej wartości bezpośrednio na stronie internetowej partnera.

API Partnera wymaga tokena, który jest unikalny dla każdego partnera i jest wysyłany z każdym żądaniem. Jeśli chcesz korzystać z API Partnera, skontaktuj się ze swoim/naszym sprzedawcą.

Format żądania

Punkt dostępu API znajduje się w /api.

Format żądania jest następujący:

<URL přístupového bodu>/<akce>[<pa­rametry>]

Wszystkie żądania są standardowymi żądaniami HTTP GET, tzn. żądanie sprawdzenia ważności vouchera może wyglądać na przykład tak:

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Format odpowiedzi

Odpowiedź serwera jest zawsze w formacie JSON z odpowiadającym jej nagłówkiem Content-type. Podstawowa struktura odpowiedzi jest następująca.

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Wartość elementu wynikowego to prawda (w przypadku powodzenia) lub fałsz (w przypadku błędu). W przypadku błędu element błędu zawiera kod błędu ( code ) i jego opis ( message ). Oprócz wskazania w polu błędu, system zwraca odpowiedni kod statusu HTTP (400, 401, 403, 404) w przypadku błędu.

Element danych zawiera dane zwrócone przez wywołaną akcję, a jego zawartość jest indywidualna.

Wszystkie dane są w formacie RRRR-MM-DDTHH:MM:SSZ (ISO8601; np. 2011–01–01T10:10:10+02:00).

Weryfikacja ważności vouchera

• akcja: voucherCheck
• parametry: token (obowiązkowy; unikalny token partnera), kod (obowiązkowy; kod vouchera)

Istnieją trzy kody kuponów testowych:

• 1234–5677–77–111 (zapłacony, nieużywany),
• 2234–5688–88–222 (płatny, używany),
• 3234–5699–99–333 (niezapłacony, niewykorzystany).

Jeżeli aplikacja użyje jednego z tych kodów, serwer zwróci odpowiednią odpowiedź (w przypadku opłaconego i niewykorzystanego vouchera zwróci również przykładowy voucher i dane dotyczące akcji).

Format danych odpowiedzi

{
 "token": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

Parametr voucherData zawiera definicję vouchera w następującym formacie.

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Elementy wariantu lub atrybut variantName zawierają identyfikator lub nazwę uporządkowanego wariantu akcji, jeśli dana akcja zawiera warianty. W przeciwnym razie oba atrybuty mają wartość NULL .

Stany błędów

• kod 1101 (kod statusu HTTP 400): nie wprowadzono tokena uwierzytelniającego lub kodu kuponu,
• kod 1102 (kod statusu HTTP 403): podany token nie znajduje się w bazie danych,
• kod 1103 (kod statusu HTTP 404): kupon o podanym kodzie nie istnieje,
• kod 1104 (kod statusu HTTP 401): zamówienie, na podstawie którego wystawiono voucher, nie zostało opłacone,
• kod 1105 (kod statusu HTTP 401): kupon został już wykorzystany,
• kod 1106 (kod statusu HTTP 401): voucher został zwrócony,
• kod 1107 (kod statusu HTTP 401): zamówienie lub kupon zostały anulowane,
• kod 1108 (kod statusu HTTP 401): akcja została już rozliczona z partnerem, nie ma możliwości zastosowania innych voucherów,
• kod 1109 (kod statusu HTTP 401): ważność voucherów na to wydarzenie jeszcze się nie rozpoczęła.
• kod 1111 (kod stanu HTTP 500): wewnętrzny błąd serwera

Przykład prośby

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Przykładowa odpowiedź

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Realizacja vouchera

• akcja: voucherApply
• parametry: token (obowiązkowy; unikalny token partnera), kod (obowiązkowy; kod vouchera)

Zostanie podjęta próba realizacji kuponu o podanym kodzie.

Możliwe jest wykorzystanie numeru vouchera testowego do celów testowych. W takim przypadku voucher nie zostanie zrealizowany, ale system zwróci odpowiedź, tak jakby miało to miejsce.

Format danych odpowiedzi

Format odpowiedzi jest dokładnie taki sam, jak w przypadku sprawdzania ważności vouchera.

Stany błędów

• kod 1201 (kod statusu HTTP 400): nie wprowadzono tokenu uwierzytelniającego lub kodu kuponu,
• kod 1202 (kod statusu HTTP 403): podany token nie znajduje się w bazie danych,
• kod 1203 (kod statusu HTTP 404): kupon o podanym kodzie nie istnieje,
• kod 1204 (kod statusu HTTP 401): zamówienie, na podstawie którego wystawiono voucher, nie zostało opłacone,
• kod 1205 (kod statusu HTTP 401): kupon został już wykorzystany,
• kod 1206 (kod statusu HTTP 401): voucher został zwrócony,
• kod 1207 (kod statusu HTTP 401): zamówienie lub kupon zostały anulowane,
• kod 1208 (kod statusu HTTP 401): akcja została już rozliczona z partnerem, nie ma możliwości zastosowania innych voucherów,
• kod 1209 (kod statusu HTTP 401): ważność voucherów na to wydarzenie jeszcze się nie rozpoczęła.
• kod 1211 (kod stanu HTTP 500): wewnętrzny błąd serwera

Przykład prośby

https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Przykładowa odpowiedź

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Uwaga: Aby użyć API Partnera do odczytu wartości lub produktów w koszyku, rozważ dodanie większej liczby atrybutów parametru voucherData. Jest to szczególnie ważne w przypadku prowadzenia kilku kampanii z różnymi wartościami oferowanych produktów. Zalecamy korzystanie głównie z atrybutów produktu lub wariantu.