Slevomat.cz Partner API

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

Możliwe przykłady użycia:

• Klient kupuje voucher, a usługa jest uzależniona od wprowadzenia kodu na stronie internetowej partnera podczas tworzenia zamówienia. Dzięki API ważność vouchera jest sprawdzana natychmiast po wprowadzeniu kodu. Wartość vouchera jest następnie odliczana z koszyka partnera, a voucher jest automatycznie realizowany w Slevomat.
• W ten sam sposób można sprawdzić ważność voucherów w systemie rezerwacyjnym partnera lub doładować zakupiony kredyt o określonej wartości bezpośrednio na stronie internetowej partnera.

Partner API wymaga tokena, który jest unikalny dla każdego partnera i jest wysyłany jako część każdego żądania. Aby użyć Partner API, skontaktuj się ze swoim/naszym przedstawicielem handlowym.

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, np. żądanie sprawdzenia ważności vouchera może wyglądać następująco:

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

Format odpowiedzi

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

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

Wartość elementu wyniku to true (w przypadku powodzenia) lub false (w przypadku błędu). W przypadku błędu wpis 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).

Walidacja kuponu

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

Dostępne są trzy kody kuponów testowych:

• 1234–5677–77–111 (opłacone, nieużywane),
• 2234–5688–88–222 (płatny, używany),
• 3234–5699–99–333 (nieopłacone, niewykorzystane).

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ładowe dane vouchera i wydarzenia).

Format danych odpowiedzi

{
 "token": <auth token>,
 "code": <voucher code>,
 "voucherData": <voucher data>
}

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

{
 "id": <Voucher ID>,
 "orderId": <Order ID>,
 "title": <voucher title>,
 "ordered": <order date and time; datetime>,
 "paidDate": <order paid date; date>
 "validFrom": <voucher validity start; date>,
 "validTo": <voucher validity end; date>,
 "key": <voucher code>,
 "code": <voucher code,
 "product": <promotion ID>,
 "productName": <promotion title>,
 "variant": <variant ID>,
 "variantName": <variant title>,
 "imageUrl": <URL image>,
 "smallImageUrl": <URL image>,
 "productUrl": <URL image>,
 "reservationTime": <Reservation time if voucher is reserved; datetime>
}

Stany błędów

• Kod 1101 (kod statusu HTTP 400): nie wprowadzono tokenu uwierzytelniającego lub kodu kuponu,
• Kod 1102 (kod statusu HTTP 403): 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 które wystawiono voucher, nie zostało opłacone,
• kod 1105 (kod statusu HTTP 401): kupon został już wykorzystany,
• kod 1106 (kod statusu HTTP 401): bon został zwrócony,
• kod 1107 (kod statusu HTTP 401): zamówienie lub kupon zostały anulowane,
• kod 1108 (kod statusu HTTP 401): wydarzenie zostało już rozliczone z partnerem; nie można już ubiegać się o kolejne vouchery,
• kod 1109 (kod statusu HTTP 401): ważność voucherów na to wydarzenie jeszcze się nie rozpoczęła,
• kod 1111 (kod statusu HTTP 500): wewnętrzny błąd serwera,
• kod 1112 (kod statusu HTTP 403): kupon musi zostać zrealizowany wyłącznie poprzez rezerwację

Przykładowa prośba

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

Przykład odpowiedzi

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

Realizacja bonu

• Akcja: voucherZastosuj
• parametry: token (obowiązkowy; unikalny token partnera), kod (obowiązkowy; kod kuponu)

Próba realizacji kuponu o podanym kodzie.

Numer kuponu testowego może być użyty do celów testowych. W tym przypadku kupon nie zostanie zrealizowany, ale system zwróci odpowiedź, tak jakby został zrealizowany.

Format danych odpowiedzi

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

Warunki błędów

• Kod 1201 (kod statusu HTTP 400): nie wprowadzono tokena uwierzytelniającego ani kodu kuponu,
• Kod 1202 (kod statusu HTTP 403): 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 które wystawiono voucher, nie zostało opłacone,
• kod 1205 (kod statusu HTTP 401): kupon został już wykorzystany,
• kod 1206 (kod statusu HTTP 401): bon został zwrócony,
• kod 1207 (kod statusu HTTP 401): zamówienie lub bon zostały anulowane,
• kod 1208 (kod statusu HTTP 401): wydarzenie zostało już rozliczone z partnerem; nie można już ubiegać się o kolejne vouchery,
• kod 1209 (kod statusu HTTP 401): ważność voucherów na to wydarzenie jeszcze się nie zaczęła,
• kod 1211 (kod statusu HTTP 500): wewnętrzny błąd serwera
• kod 1212 (kod statusu HTTP 403): voucher można zrealizować wyłącznie poprzez rezerwację

Przykładowa prośba

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

Przykład odpowiedzi

{
 "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 odliczenia wartości lub produktów w koszyku, rozważ uwzględnienie wielu atrybutów parametru voucherData. Jest to szczególnie ważne, gdy masz wiele bieżących promocji z różną wartością oferowanych produktów. W szczególności zalecamy użycie atrybutów produktu lub wariantu.