Az API az utalványokra vonatkozó információk átvitelére szolgál a Slevomat és az üzleti partner rendszere között. Lehetővé teszi a partner számára, hogy ellenőrizze az utalványok érvényességét a rendszerében, és beváltsa az utalványokat. A partnernek ehhez nem kell a partner interfészt használnia.
Lehetséges felhasználási példák:
- Egy ügyfél olyan utalványt vásárol, ahol a szolgáltatás igénybevételének feltétele, hogy a partner weboldalán a megrendelés létrehozásakor megadja a kódot. Az API-nak köszönhetően az utalvány érvényessége a bevitel után azonnal ellenőrizhető. 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 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-nak szüksége van egy tokenre, amely minden egyes partner esetében egyedi, és amelyet minden egyes kérés részeként küldünk el. A partner API használatához kérjük, lépjen kapcsolatba az Ön/ön értékesítési képviselőjével.
Kérés formátuma
Az API hozzáférési pont a /api címen található.
A kérés formátuma a következő
<URL přístupového bodu>/<akce>[<parametry>]
Minden kérés szabványos HTTP GET-kérés, azaz egy 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álaszformátum
A kiszolgáló válasza mindig JSON formátumú, a megfelelő Content-type fejléccel. A válasz alapvető szerkezete a következő.
{
"result": true,
"data": {
...
},
"error": {
"code": 0,
"message": null
}
}
Az eredményelem értéke true (siker esetén) vagy false (hiba esetén). Hiba esetén a hibaelem tartalmazza a hibakódot (kód) és annak leírását (üzenet). A hiba mezőben szereplő jelzésen kívül a rendszer hiba esetén a megfelelő HTTP státuszkódot (400, 401, 403, 404) is visszaadja.
Az adatelem a meghívott művelet által visszaküldött adatokat tartalmazza, és tartalma egyedi.
Minden adat az ÉÉÉÉÉ-HH-HH-HH:MM:SSZ (ISO8601; pl. 2011–01–01–01T10:10:10:10+02:00) formátumú.
Utalvány érvényesítés
- művelet: voucherCheck
- paraméterek: token (kötelező; egyedi partner token), kód (kötelező; utalványkód)
Három teszt utalványkód létezik:
- 1234–5677–77–111 (fizetett, fel nem használt),
- 2234–5688–88–222 (kifizetett, használt),
- 3234–5699–99–333 (kifizetetlen, nem használt).
Ha az alkalmazás ezen kódok valamelyikét használja, a szerver a megfelelő választ küldi vissza (kifizetett és fel nem használt utalvány esetén az utalvány és az esemény adatainak mintáját is).
A válasz adatformátuma
{
"token": <autentizační token>,
"code": <kód voucheru>,
"voucherData": <data voucheru>
}
A voucherData paraméter az utalvány definícióját tartalmazza a következő formátumban.
{
"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>
}
A variant és variantName mezők az esemény megrendelt változatának azonosítóját vagy nevét tartalmazzák, ha az esemény tartalmaz változatokat. Ha nem, akkor mindkét attribútum NULL.
Hibaállapotok
- 1101-es kód (400-as HTTP státuszkód): hitelesítési token vagy utalványkód nem került megadásra,
- 1102-es kód (403-as HTTP státuszkód): a token nincs az adatbázisban,
- 1103-as kód (404-es HTTP státuszkód): a megadott kódú utalvány nem létezik,
- 1104-es kód (401-es HTTP státuszkód): az utalvány kiállításának alapjául szolgáló megrendelés nem került kifizetésre,
- kód 1105 (HTTP státuszkód 401): az utalványt már beváltották,
- 1106. kód (HTTP státuszkód 401): az utalványt már visszaváltották,
- 1107-es kód (401-es HTTP státuszkód): a rendelés vagy az utalvány törlésre került,
- 1108-as kód (401-es HTTP státuszkód): az eseményt már kiszámlázták a partnernek; további utalványt nem lehet igényelni,
- 1109-es kód (HTTP státuszkód 401): az eseményre vonatkozó utalványok még nem kezdtek érvényessé válni,
- 1111-es kód (HTTP státuszkód 500): belső szerverhiba,
- 1112-es kód (403-as HTTP státuszkód): az utalványt csak foglalással lehet beváltani.
Példa kérés
https://www.slevomat.cz/api/vouchercheck?code=1234-5677-77-111&token=123456789012345
Példa a válaszra
{
"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: voucherApply
- paraméterek: token (kötelező; egyedi partner token), kód (kötelező; utalványkód)
Megkísérli beváltani a megadott kódú utalványt.
A tesztutalvány száma tesztelési célokra használható. Ebben az esetben az utalvány nem kerül beváltásra, de a rendszer olyan választ küld vissza, mintha beváltották volna.
A válasz adatformátuma
A válasz formátuma pontosan megegyezik az utalvány érvényességének ellenőrzésével.
Hibakörülmények
- 1201-es kód (400-as HTTP státuszkód): nem adtak meg hitelesítési tokent vagy utalványkódot,
- 1202-es kód (403-as HTTP státuszkód): a token nincs az adatbázisban,
- 1203-as kód (404-es HTTP státuszkód): a megadott kódú utalvány nem létezik,
- 1204-es kód (401-es HTTP státuszkód): az utalvány kiállításának alapjául szolgáló megrendelés nem került kifizetésre,
- 1205-ös kód (HTTP státuszkód 401): az utalványt már beváltották,
- 1206-os kód (HTTP státuszkód 401): az utalványt visszaváltották,
- 1207-es kód (401-es HTTP státuszkód): a rendelés vagy az utalvány törlésre került,
- 1208-as kód (401-es HTTP státuszkód): az eseményt már kiszámlázták a partner felé; további utalványt nem lehet igényelni,
- 1209-es kód (HTTP státuszkód 401): az eseményre vonatkozó utalványok még nem jártak le,
- 1211-es kód (500-as HTTP státuszkód): belső szerverhiba.
- 1212-es kód (403-as HTTP státuszkód): az utalványt csak foglalással lehet beváltani.
Példa kérés
https://www.slevomat.cz/api/voucherapply?code=1234-5677-77-111&token=123456789012345
Példa a válaszra
{
"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 a kosárban lévő érték vagy termékek levonására szeretné használni, fontolja meg a voucherData paraméter több attribútumának megadását. Ez különösen akkor fontos, ha több promóciója is fut, különböző értékű termékekkel. Különösen javasoljuk a termék vagy a variáns attribútumok használatát.