Slevomat.cz partner API

Az API az utalványinformációknak a Discountomat és a kereskedő rendszere közötti átvitelére szolgál. 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 nem kell ehhez a partneri interfészt használnia.

Lehetséges felhasználási példák:

• Egy vásárló utalványt vásárol, ahol a szolgáltatás feltétele, hogy a megrendelés létrehozásakor a partner weboldalán meg kell adni egy kódot. Az API-nak köszönhetően az utalvány érvényességét a bevitel után azonnal ellenőrzi a rendszer. Ezt követően az értéke levonásra kerül a partner kosarában, és ezzel egyidejűleg az utalvány automatikusan beváltásra kerül a Discountomatban.
• 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 megvásárolt, meghatározott értékű kredit feltöltésére a vásárlónak 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 elküldünk. A partner API használatához kérjük, lépjen kapcsolatba a kereskedőjével/kereskedőinkkel.

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>[<pa­rametry>]

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.zlavomat.sk/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 a YYYY-MM-DDTHH: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.

Hibakörülmények

• 1101-es kód (400-as HTTP státuszkód): a hitelesítési jelszót vagy az utalványkódot nem adták meg,
• 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 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ányok nem igényelhetők,
• 1109-es kód (HTTP státuszkód 401): az eseményre vonatkozó utalványok még nem jártak le.
• 1111-es kód (HTTP státuszkód 500): belső szerverhiba.

Példa kérés

https://www.zlavomat.sk/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 ugyanaz, mint az utalvány érvényességének ellenőrzése esetén.

Hibakörülmények

• 1201-es kód (400-as HTTP státuszkód): a hitelesítési token vagy az utalványkód nem került megadásra,
• 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.

Példa kérés

https://www.zlavomat.sk/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ő termékek értékének levonására szeretné használni, fontolja meg, hogy több attribútumot is megadjon a voucherData paraméterhez. Ez különösen akkor fontos, ha a voucher paramétert szeretné használni. Ez akkor fontos, ha több futó promóciója van különböző termékértékekkel. Különösen javasoljuk a termék vagy variáns attribútumok használatát.