Slevomat.cz Partner API

API jest używane do przesyłania informacji o voucherach pomiędzy Zľavomat a systemem partnera biznesowego. Umożliwia partnerowi weryfikację ważności voucherów oraz ich realizację w swoim własnym systemie. Dzięki temu partner nie musi korzystać z Interfejsu Partnerskiego w tym celu.

Przykłady możliwego użycia:

• Klient kupuje voucher, gdzie wymagane jest wpisanie kodu na stronie partnera, aby zrealizować usługę podczas składania zamówienia. Dzięki API ważność vouchera jest sprawdzana natychmiast po wpisaniu kodu. Jego wartość jest następnie odliczana w koszyku partnera, a jednocześnie voucher jest automatycznie realizowany w Zľavomat.
• Ważność voucherów może być również sprawdzana w systemie rezerwacyjnym partnera w ten sam sposób, lub zakupiony kredyt o określonej wartości może być bezpośrednio przypisany do konta klienta na stronie partnera.

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

Format żądania

Punkt końcowy API znajduje się pod /api.

Format żądania to

<API endpoint URL>/<action>[<parameters>]

Wszystkie żądania to standardowe żądania HTTP GET, tzn. żądanie sprawdzenia ważności vouchera może wyglądać następująco:

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

Format odpowiedzi

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

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

Wartość elementu result to true (w przypadku sukcesu) lub false (w przypadku błędu). W przypadku błędu element error zawiera kod błędu (code) oraz jego opis (message). Oprócz wskazania w polu error, system zwraca również odpowiedni kod statusu HTTP (400, 401, 403, 404) w przypadku błędu.

Element data zawiera dane zwracane przez wywołaną akcję, a jego zawartość jest indywidualna.

Wszystkie daty są w formacie YYYY-MM-DDTHH:MM:SSZ (ISO8601; np. 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Sprawdzenie ważności vouchera

• akcja: voucherCheck
• parametry: token (wymagany; unikalny token partnera), code (wymagany; kod vouchera)

Istnieją trzy testowe kody voucherów:

• 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (opłacony, nieużyty),
• 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (opłacony, użyty),
• 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (nieopłacony, nieużyty).

Jeśli aplikacja użyje jednego z tych kodów, serwer zwróci odpowiednią odpowiedź (w przypadku opłaconego i nieużytego vouchera zwróci również przykładowe dane vouchera i akcji).

Format danych odpowiedzi

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

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

{
 "id": <voucher ID>,
 "orderId": <order ID>,
 "title": <nazwa vouchera>,
 "ordered": <data i godzina zamówienia; data i godzina>,
 "paidDate": <data opłacenia zamówienia; data>
 "validFrom": <początek ważności vouchera; data>,
 "validTo": <koniec ważności vouchera; data>,
 "key": <kod vouchera>,
 "code": <kod vouchera>,
 "product": <ID akcji>,
 "productName": <nazwa akcji>,
 "variant": <ID wariantu akcji>,
 "variantName": <nazwa wariantu akcji>,
 "imageUrl": <URL obrazka>,
 "smallImageUrl": <URL miniatury>,
 "productUrl": <URL akcji>
}

Elementy variant oraz variantName zawierają ID i nazwę zamówionego wariantu akcji, jeśli dana akcja posiada warianty. Jeśli nie, oba atrybuty mają wartość NULL.

Stany błędów

• kod 1101 (kod statusu HTTP 400): nie podano tokena uwierzytelniającego lub kodu vouchera,
• kod 1102 (kod statusu HTTP 403): podany token nie znajduje się w bazie danych,
• kod 1103 (kod statusu HTTP 404): voucher o podanym kodzie nie istnieje,
• kod 1104 (kod statusu HTTP 401): zamówienie, na podstawie którego wydano voucher, nie zostało opłacone,
• kod 1105 (kod statusu HTTP 401): voucher został już zrealizowany,
• kod 1106 (kod statusu HTTP 401): voucher został zwrócony,
• kod 1107 (kod statusu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1108 (kod statusu HTTP 401): akcja została już rozliczona z partnerem; nie można zrealizować więcej voucherów,
• kod 1109 (kod statusu HTTP 401): ważność voucherów dla tej akcji jeszcze się nie rozpoczęła.
• kod 1111 (kod statusu HTTP 500): wewnętrzny błąd serwera

Przykład żądania

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

Przykład odpowiedzi

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <nazwa vouchera>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Realizacja vouchera

• akcja: voucherApply
• parametry: token (wymagany; unikalny token partnera), code (wymagany; kod vouchera)

Próba realizacji vouchera o podanym kodzie.

Do celów testowych można użyć testowego numeru vouchera. W takim przypadku voucher nie zostanie faktycznie zrealizowany, ale system zwróci odpowiedź, jakby został.

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 podano tokena uwierzytelniającego lub kodu vouchera,
• kod 1202 (kod statusu HTTP 403): podany token nie znajduje się w bazie danych,
• kod 1203 (kod statusu HTTP 404): voucher o podanym kodzie nie istnieje,
• kod 1204 (kod statusu HTTP 401): zamówienie, na podstawie którego wydano voucher, nie zostało opłacone,
• kod 1205 (kod statusu HTTP 401): voucher został już zrealizowany,
• kod 1206 (kod statusu HTTP 401): voucher został zwrócony,
• kod 1207 (kod statusu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1208 (kod statusu HTTP 401): akcja została już rozliczona z partnerem; nie można zrealizować więcej voucherów,
• kod 1209 (kod statusu HTTP 401): ważność voucherów dla tej akcji jeszcze się nie rozpoczęła.
• kod 1211 (kod statusu HTTP 500): wewnętrzny błąd serwera

Przykład żądania

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

Przykład odpowiedzi

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <nazwa vouchera>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Uwaga: Przy korzystaniu z Partner API do odliczania wartości lub produktów w koszyku, rozważ uwzględnienie większej liczby atrybutów parametru voucherData. Jest to szczególnie ważne, gdy masz kilka trwających akcji z różnymi wartościami oferowanych produktów. Zalecamy szczególnie korzystanie z atrybutów product lub variant.