Exareg - Komunikačný protokol

Špecifikácia webových služieb Asseco BLUEGASTROWS

História dokumentácie

Dátum vydania	Verzia dokumentu	Popis zmien	Autor
20.07.2015	1.0	Založenie dokumentácie.	Juraj Pacolt
28.01.2016	1.1	Modul Exareg, doplnená kontrola duplicity emailu pri volaní metódy sendGuestInfo.	Juraj Pacolt
29.01.2016	1.2	Modul ExternalOrders, doplnená nová metóda modifyCredit.	Juraj Pacolt

Popis

Rozšírenie Asseco BLUEGASTROWS je sada webových služieb vystavených zo systemu Asseco BLUEGASTRO. Tieto služby maju za úlohu zastrešiť potrebnú funkcionalitu pre externé systémy.

Komunikačný interface využíva na prenos správ protokol HTTP, prípadne HTTPS. Jednotlivé dotazy sú typu REST, tzn. štandardné URI linky s prípadnými parametrami. Pričom niektoré požiadavky prípadne návratové správy, resp. odpovede sú typu JSON. Ako content type sa očakáva application/json.

V každej metóde komunikácie je potrebné uviesť systemId. Toto ID systému je číslo zaregistrovaného externého systému v systéme Asseco BLUEGASTRO. Pokiaľ sa dané číslo nenájde v zozname zaregistrovaných externých systémov, prípadne pokiaľ má externý systém zablokovanú komunikáciu, resp. nie je povolený, systém Asseco BLUEGASTRO nedovolí vykonať požiadavku.

Modul "Registrácia stálych hostí" (Exareg)

Metóda "test"

Metóda test slúži iba na preverenie komunikácie a validáciu základnej funkčnosti modulu Exareg.

http://server:port/Asseco BLUEGASTROWS/rest/Exareg/test/{input}

Vstupné parametre

• input - Testovacia správa.

Požiadavka

<code>
GET http://server:port/Asseco BLUEGASTROWS/rest/Exareg/test/Testovaci retazec ...
</code>

JSON návratovej správy

<code>
... cezater icavotseT
</code>

Metóda "getVersion"

Metóda getVersion slúži na získanie verzie webových služieb modulu Exareg.

http://server:port/Asseco BLUEGASTROWS/rest/Exareg/getVersion/{systemId}

Vstupné parametre

• systemId - Číslo pod ktorým je zaregistrovaný externý systém v systéme Asseco BLUEGASTRO.

Požiadavka

<code>
GET http://server:port/Asseco BLUEGASTROWS/rest/Exareg/getVersion/1234567890
</code>

JSON návratovej správy

<code>
2
</code>

Metóda "sendGuestInfo"

Volanie metódy zabezpečí vytvorenie stáleho hosťa v systéme Asseco BLUEGASTRO. Metódu je možné zavolať dvoma spôsobmi. Druhý spôsob slúži na aktualizáciu údajov hosťa. Aktualizáciu je možné využiť aj pri prvom spôsobe s tým, že je potrebné v rámci štruktúry hosťa uviesť jeho ID.

http://server:port/Asseco BLUEGASTROWS/rest/Exareg/sendGuestInfo/{systemId}

http://server:port/Asseco BLUEGASTROWS/rest/Exareg/sendGuestInfo/{systemId}/{guestId}

Vstupné parametre

• systemId - Číslo pod ktorým je zaregistrovaný externý systém v systéme Asseco BLUEGASTRO.
• guestId - Jednoznačné identifikačné číslo hosťa v systéme Asseco BLUEGASTRO.

Požiadavka

<code>
POST http://server:port/Asseco BLUEGASTROWS/rest/Exareg/sendGuestInfo/1234567890<br><br>
PUT http://server:port/Asseco BLUEGASTROWS/rest/Exareg/sendGuestInfo/1234567890/99975
</code>

JSON požiadavky

<code>
{
    "addressCity": "Bratislava",
    "addressStreet": "Plynárenská 7/C",
    "addressZip": "82109",
    "countryCode": "SVK",
    "dateOfBirth": "1980-01-01T00:00:00.000Z",
    "email": "asol@assecosol.eu",
    "firstname": "Janko",
    "lastname": "Hraško",
    "note": "Poznámka ...",
    "telephoneNumber": "0903123456"
}
</code>

• guestId - ID hosťa - jednoznačné identifikačné číslo hosťa v systéme Asseco BLUEGASTRO.
• addressCity - Mesto.
• addressStreet - Ulica.
• addressZip - Poštové smerovacie číslo (<a target="_blank" href="https://sk.wikipedia.org/wiki/Po%C5%A1tov%C3%A9_smerovacie_%C4%8D%C3%ADslo">PSČ</a>).
• countryCode - Kód krajiny - štátu.
• dateOfBirth - Dátum narodenia (<a target="_blank" href="https://sk.wikipedia.org/wiki/ISO_8601">ISO 8601</a>).
• email - Kontaktný email.
• firstname - Meno hosťa.
• lastname - Priezvisko hosťa.
• note - Poznámka k hosťovi.
• telephoneNumber - Kontaktné telefónne číslo.
• cardNumber - Číslo karty. Pokiaľ sa neuvedie a je to povolené v systéme Asseco BLUEGASTRO, tak sa číslo karty vygeneruje a automaticky prideli danému hosťovi.
• ean - Kód EAN, ktorý sa pridelí hosťovi.
• titleCode - Kód oslovenia.
• documentNumber - Číslo dokladu.
• documentTypeCode - Typ dokladu.

JSON návratovej správy

<code>
{
    "guestId": 99975,
    "cardNumber": "7440004002012",
    "returnMessage": {
        "code": 0,
        "message": "Successful",
        "stackTrace": null
    }
}
</code>

• guestId - ID hosťa.
• cardNumber - Číslo pridelenej karty, prípadne vygenerované.
• returnMessage - Návratová správa.
  • code - Kód správy / hlásenia.
  • message - Text správy.
  • stackTrace - V prípade chyby, celý - systémový výpis (nie je vhodné zobrazovať pre používateľa).

Návratové kódy

Jednotlivé metódy v časti returnMessage pri návratovej správe vracajú kód aj správu ako daná požiadavka dopadla. V nasledujúcej tabuľke je zoznam všetkých návratových kódov, ktoré môžu nastať.

Kód	Popis
-1	Bližšie nešpecifikovaná systémová chyba.
0	Všetko je v poriadku. Požiadavka bola spracovaná.
1	Neznáma chyba.
2	Číslo karty je už použité pre niekoho iného.
3	Nevyplnené povinné údaje.
4	Emailová adresa je už pridelená inému hosťovi.
5	Server nemôže bežať v SLAVE móde.