Slevomat.cz Partner API

API służy do przesyłania informacji o voucherach między Slevomat a systemem partnera biznesowego. Pozwala to partnerowi zweryfikować ważność voucherów w swoim systemie i zrealizować vouchery. Partner nie musi w tym celu korzystać z interfejsu partnerskiego.

Możliwe przykłady użycia:

• Klient kupuje voucher, w którym warunkiem realizacji usługi jest wpisanie kodu na stronie partnera podczas tworzenia zamówienia. Dzięki API ważność bonu jest sprawdzana natychmiast po jego wprowadzeniu. Wartość vouchera jest następnie odejmowana od koszyka partnera, a voucher jest automatycznie realizowany w Slevomat.
• W ten sam sposób można również sprawdzić ważność voucherów w systemie rezerwacji partnera lub przesłać 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 skorzystać z interfejsu Partner API, należy skontaktować się z naszym przedstawicielem handlowym.

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, tj. żą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 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 pozycja błędu zawiera kod błędu ( code) i jego opis (message). Oprócz wskazania w polu błędu, system zwraca odpowiedni kod stanu 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 YYYY-MM-DDTHH:MM:SSZ (ISO8601; np. 2011–01–01T10:10:10+02:00).

Walidacja kuponu

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

Istnieją trzy kody voucherów testowych:

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

Jeśli 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 zdarzenia).

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>
}

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.

Stany błędów

• Kod 1101 (kod stanu HTTP 400): nie wprowadzono tokena uwierzytelniającego lub kodu vouchera,
• Kod 1102 (kod stanu HTTP 403): token nie znajduje się w bazie danych,
• kod 1103 (kod stanu HTTP 404): voucher o podanym kodzie nie istnieje,
• kod 1104 (kod stanu HTTP 401): zamówienie, na podstawie którego wydano voucher, nie zostało opłacone,
• kod 1105 (kod stanu HTTP 401): voucher został już zrealizowany,
• kod 1106 (kod stanu HTTP 401): bon został zwrócony,
• kod 1107 (kod stanu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1108 (kod stanu HTTP 401): wydarzenie zostało już rozliczone z partnerem; nie można ubiegać się o kolejne vouchery,
• kod 1109 (kod stanu HTTP 401): vouchery na to wydarzenie nie zaczęły jeszcze obowiązywać,
• kod 1111 (kod stanu HTTP 500): wewnętrzny błąd serwera,
• kod 1112 (kod stanu HTTP 403): voucher musi zostać zrealizowany wyłącznie poprzez rezerwację

Przykładowe żądanie

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 kuponu

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

Próbuje zrealizować voucher o podanym kodzie.

Numer bonu testowego może być używany do celów testowych. W takim przypadku voucher 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 sprawdzania ważności vouchera.

Warunki błędu

• Kod 1201 (kod stanu HTTP 400): nie wprowadzono tokena uwierzytelniającego ani kodu vouchera,
• Kod 1202 (kod stanu HTTP 403): token nie znajduje się w bazie danych,
• kod 1203 (kod stanu HTTP 404): voucher o podanym kodzie nie istnieje,
• kod 1204 (kod stanu HTTP 401): zamówienie, na podstawie którego wydano voucher, nie zostało opłacone,
• kod 1205 (kod stanu HTTP 401): voucher został już zrealizowany,
• kod 1206 (kod stanu HTTP 401): bon został zwrócony,
• kod 1207 (kod stanu HTTP 401): zamówienie lub voucher zostały anulowane,
• kod 1208 (kod stanu HTTP 401): wydarzenie zostało już rozliczone z partnerem; nie można ubiegać się o kolejne vouchery,
• kod 1209 (kod stanu HTTP 401): vouchery na to wydarzenie nie zaczęły jeszcze wygasać,
• kod 1211 (kod stanu HTTP 500): wewnętrzny błąd serwera
• kod 1212 (kod stanu HTTP 403): voucher może być zrealizowany tylko poprzez rezerwację

Przykładowe żądanie

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ć Partner API do odliczenia wartości lub produktów w koszyku, należy rozważyć włączenie wielu atrybutów parametru voucherData. Jest to szczególnie ważne w przypadku wielu trwających promocji o różnej wartości oferowanych produktów. W szczególności zalecamy użycie atrybutów produktu lub wariantu.