Slevomat.cz Partner API

API służy do przesyłania informacji o kuponach między Dyskontomatem a systemem handlowca. Dzięki temu partner może sprawdzić ważność kuponów w swoim systemie i zrealizować kupony. Partner nie musi w tym celu korzystać z interfejsu partnerskiego.

Możliwe przykłady użycia:

• Klient kupuje voucher, gdzie warunkiem realizacji usługi jest wpisanie kodu na stronie partnera podczas tworzenia zamówienia. Dzięki API, po wprowadzeniu kodu, voucher jest natychmiast sprawdzany pod kątem ważności. Jego wartość jest następnie odliczana w koszyku partnera i jednocześnie bon jest automatycznie realizowany w Discountomat.
• W ten sam sposób można również sprawdzić ważność bonów w systemie rezerwacji partnera lub przesłać klientowi zakupiony kredyt o określonej wartości bezpośrednio na stronie partnera.

Interfejs API Partnera wymaga tokena, który jest unikalny dla każdego partnera i jest wysyłany w ramach każdego żądania. Aby skorzystać z interfejsu API Partnera, należy skontaktować się z naszym handlowcem.

Format żądania

Punkt dostępu API znajduje się pod adresem /api.

Format żądania to

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

Wszystkie żądania są standardowymi żądaniami HTTP GET, tzn. żądanie sprawdzenia ważności kuponu 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ścią elementu result jest true (w przypadku sukcesu) lub false (w przypadku błędu). W przypadku błędu pozycja błędu zawiera kod błędu(code) i jego opis(message). Oprócz wskazania w polu błędu, w przypadku wystąpienia błędu system zwraca odpowiedni kod statusu HTTP (400, 401, 403, 404).

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

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

Walidacja bonów

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

Istnieją trzy testowe kody voucherów:

• 1234–5677–77–111 (opłacony, niewykorzystany),
• 2234–5688–88–222 (opłacony, wykorzystany),
• 3234–5699–99–333 (nieopłacony, niewykorzystany).

Jeśli aplikacja użyje jednego z tych kodów, serwer odeśle odpowiednią odpowiedź (w przypadku opłaconego i niewykorzystanego bonu odeśle również przykładowe dane bonu i zdarzenia).

Format danych odpowiedzi

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

Parametr voucherData zawiera definicję bonu 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>
}

Pola variant i variantName zawierają identyfikator lub nazwę zamówionego wariantu zdarzenia, jeśli zdarzenie zawiera warianty. Jeśli nie, oba atrybuty mają wartość NULL.

Warunki błędu

• Kod 1101 (kod statusu HTTP 400): nie wprowadzono tokena uwierzytelniającego lub kodu kuponu,
• Kod 1102 (kod statusu HTTP 403): tokena nie ma 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 został wystawiony bon nie zostało opłacone,
• kod 1105 (kod statusu HTTP 401): bon został już zrealizowany,
• kod 1106 (kod statusu HTTP 401): bon został zwrócony,
• kod 1107 (kod statusu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1108 (HTTP status code 401): zdarzenie zostało już rozliczone z partnerem, nie można żądać dalszych voucherów,
• kod 1109 (kod statusu HTTP 401): termin ważności voucherów na to wydarzenie jeszcze nie upłynął.
• kod 1111 (kod statusu HTTP 500): wewnętrzny błąd serwera.

Przykładowe zapytanie

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": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Realizacja vouchera

• Akcja: voucherApply
• parametry: token (obowiązkowo; unikalny token partnera), kod (obowiązkowo; kod bonu)

Próbuje zrealizować voucher o podanym kodzie.

Numer vouchera testowego może być użyty do celów testowych. W tym przypadku bon 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 kontroli ważności bonu.

Warunki błędu

• Kod 1201 (kod statusu HTTP 400): nie wprowadzono tokena uwierzytelniającego lub kodu bonu,
• kod 1202 (kod statusu HTTP 403): tokena nie ma w bazie danych,
• kod 1203 (kod statusu HTTP 404): voucher o podanym kodzie nie istnieje,
• kod 1204 (HTTP status code 401): zamówienie, na podstawie którego został wystawiony bon nie zostało opłacone,
• kod 1205 (HTTP status code 401): bon został już zrealizowany,
• kod 1206 (kod statusu HTTP 401): bon został zwrócony,
• kod 1207 (kod statusu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1208 (HTTP status code 401): zdarzenie zostało już rozliczone z partnerem, nie można żądać dalszych bonów,
• kod 1209 (kod statusu HTTP 401): termin ważności voucherów na to wydarzenie jeszcze nie upłynął.
• kod 1211 (kod statusu HTTP 500): wewnętrzny błąd serwera

Przykładowe zapytanie

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": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Uwaga: Aby użyć API Partnera do odliczenia wartości lub produktów w koszyku, rozważ włączenie wielu atrybutów do parametru voucherData. Jest to ważne, zwłaszcza jeśli chcesz użyć parametru voucher. Jest to ważne, gdy masz wiele działających promocji z różnymi wartościami produktów. W szczególności, zalecamy użycie atrybutów produktu lub wariantu.