Az API az utalványokkal kapcsolatos információk továbbítására szolgál a Slevomat és az üzleti partner rendszere között. Lehetővé teszi a partner számára, hogy a rendszerében ellenőrizze az utalványok érvényességét, és beváltsa az utalványokat. A partnernek erre a célra nem kell használnia a Partner felületet.
Lehetséges felhasználási példák:
- A vásárló olyan utalványt vásárol, ahol a szolgáltatás feltétele, hogy a megrendelés létrehozásakor kódot adjon meg a partner honlapján. Az API-nak köszönhetően az utalvány érvényessége e bejegyzés után azonnal ellenőrzésre kerül. Ezután az utalvány értéke levonásra kerül a partner kosarából, és az utalvány automatikusan beváltásra kerül a Slevomatnál.
- Ugyanígy lehetőség van az utalványok érvényességének ellenőrzésére is a partner foglalási rendszerében, vagy egy bizonyos értékű vásárolt kredit feltöltésére közvetlenül a partner weboldalán.
A Partner API-hoz olyan tokenre van szükség, amely minden partner esetében egyedi , és minden kérés részeként kerül elküldésre. A Partner API használatához vegye fel a kapcsolatot értékesítési képviselőjével.
Kérelem formátuma
Az API hozzáférési pont a /api címen található.
A kérés formátuma
<URL přístupového bodu>/<akce>[<parametry>]
Minden kérés szabvány HTTP GET kérés, azaz az utalvány érvényességének ellenőrzésére irányuló kérés így nézhet ki:
https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.
Válasz formátum
A kiszolgáló válasza mindig JSON formátumban van a megfelelő tartalomtípusú fejléccel együtt. A válasz alapvető felépítése a következő.
{
"result": true,
"data": {
...
},
"error": {
"code": 0,
"message": null
}
}
Az eredményelem értéke igaz (siker esetén) vagy false (hiba esetén). Hiba esetén a hibabejegyzés tartalmazza a hibakódot (kód ) és annak leírását (üzenet ). A hibamező jelzése mellett a rendszer hiba esetén a megfelelő HTTP állapotkódot (400, 401, 403, 404) is visszaadja.
Az adatelem a hívott művelet által visszaadott adatokat tartalmazza, tartalma egyedi.
Minden adat ÉÉÉÉ-HH-NNTHH:MM:SSZ (ISO8601; pl. 2011–01–01T10:10:10+02:00) formátumú.
Az utalvány érvényesítése
- művelet: utalványcsekk
- paraméterek: token (kötelező; egyedi partner token), kód (kötelező; utalvány kód)
Három tesztutalvány kódja van:
- 1234–5677–77–111 (fizetett, nem használt),
- 2234–5688–88–222 (fizetett, használt),
- 3234–5699–99–333 (nem fizetett, nem használt).
Ha az alkalmazás ezen kódok valamelyikét használja, a szerver visszaküldi a megfelelő választ (kifizetett és fel nem használt voucher esetén minta utalvány- és eseményadatokat is visszaküld).
Válasz adatformátum
{
"token": <auth token>,
"code": <voucher code>,
"voucherData": <voucher data>
}
A voucherData paraméter az utalvány definícióját tartalmazza a következő formátumban.
{
"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>
}
Hibaállapotok
- 1101-es kód (400-as HTTP-állapotkód): a hitelesítési tokent vagy az utalványkódot nem adta meg,
- Kód 1102 (HTTP állapotkód 403): a token nincs az adatbázisban,
- kód 1103 (HTTP állapotkód 404): a megadott kóddal rendelkező utalvány nem létezik,
- kód 1104 (HTTP státuszkód 401): az utalvány kiállításának megrendelését nem fizették ki,
- kód 1105 (HTTP állapotkód 401): az utalványt már beváltották,
- kód 1106 (HTTP állapotkód 401): az utalványt visszatérítették,
- kód 1107 (HTTP állapotkód 401): a rendelést vagy az utalványt törölték,
- kód 1108 (HTTP állapotkód 401): az eseményt már kiszámlázták a partnernek; további utalvány nem igényelhető,
- kód 1109 (HTTP állapotkód 401): az eseményre vonatkozó utalványok még nem kezdték el érvényesíteni,
- kód 1111 (HTTP állapotkód 500): belső szerverhiba,
- kód 1112 (HTTP állapotkód 403): az utalvány csak foglalással váltható be
Példa kérés
https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345
Példa a válaszadásra
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Utalvány beváltása
- Művelet: utalvány Jelentkezés
- paraméterek: token (kötelező; egyedi partner token), kód (kötelező; utalvány kód)
Megpróbálja beváltani a megadott kód kuponját.
A tesztutalvány száma tesztelési célokra használható fel. Ebben az esetben az utalvány nem kerül beváltásra, hanem a rendszer olyan választ ad vissza, mintha beváltották volna.
Válasz adatformátum
A válasz formátuma pontosan ugyanaz, mint az utalvány érvényességi ellenőrzésénél.
Hibafeltételek
- Kód 1201 (HTTP állapotkód 400): nem adtak meg hitelesítési tokent vagy utalványkódot,
- Kód 1202 (HTTP állapotkód 403): a token nincs az adatbázisban,
- kód 1203 (HTTP állapotkód 404): a megadott kóddal rendelkező utalvány nem létezik,
- kód 1204 (HTTP állapotkód 401): az utalvány kiállításának megrendelését nem fizették ki,
- kód 1205 (HTTP állapotkód 401): az utalványt már beváltották,
- kód 1206 (HTTP állapotkód 401): az utalványt visszatérítették,
- kód 1207 (HTTP állapotkód 401): a rendelést vagy az utalványt törölték,
- kód 1208 (HTTP állapotkód 401): az eseményt már kiszámlázták a partnernek; további utalvány nem igényelhető,
- 1209-es kód (401-es HTTP-állapotkód): az eseményre vonatkozó utalványok még nem jártak le,
- kód 1211 (HTTP állapotkód 500): belső szerverhiba
- kód 1212 (HTTP állapotkód 403): az utalványt csak foglalással kell beváltani
Példa kérés
https://www.slevomat.cz/api/voucherapply?code=1234-5677-77-111&token=123456789012345
Példa a válaszadásra
{
"result": true,
"data": {
"token": "123456789012345",
"code": "1234567890-123",
"voucherData": {
"title": <název voucheru>,
...
}
},
"error": {
"code": 0,
"message": null
}
}
Megjegyzés: Ha a Partner API-t szeretné használni a kosárban lévő érték vagy termékek levonására, fontolja meg a voucherData paraméter több attribútumának megadását. Ez különösen fontos, ha több promóciója van, amelyekben a kínált termékek értéke eltérő. Különösen a termék- vagy változatattribútumok használatát javasoljuk.