Az adatkapcsolat teszteléséhez szükséged lesz egy teszt API kulcsra, amit e-mailben tudsz tőlünk kérni. Kérjük írj az info@orsys.hu e-mail címre és jelentkezésedben add meg a következő adatokat is:
Az Orsys felé intézett minden API kérésben jelen kell lennie a headerben az X-API-Key elemnek, aminek tartalmaznia kell az összekötés API kulcsát.
Ezt a végpontot kell használni, amikor egy véglegesített rendelést szeretnél átadni az Orsys rendszerének.
Végpont: https://api.orsys.hu/webhook/plugin
Az adatokat a body-ban JSON formátumban kell elküldeni, POST kérésként. Jobb oldalt a minta kód egy példa JSON kérést tartalmaz.
A teljes rendelés felépítése.
Változó | Típus | Kötelező | Leírás | |
---|---|---|---|---|
remoteId | String | igen | Éttermen belüli egyedi rendelésazonosító | |
paymentType | String | igen | Fizetési mód. Online fizetésnél állítani kell a paidAmount értéket is. | |
scheduledTime | DateTime | nem | Időre rendelés esetén a kért idő. ISO_OFFSET_DATE_TIME formátumban (ISO 8601 szerint + időzóna, pl: 2023-09-13T18:17:30+02:00) | |
takeAway | Boolean | nem | Elviteles rendelés esetén igaz értéket kell kapnia. | |
customer | Array | igen | Vásárló adatait tartalmazó vektor. | |
name | String | igen | Vásárló teljes neve. | |
phone | String | igen | Vásárló telefonszáma. Elvárt formátum: +36205230949 | |
String | nem | Vásárló e-mail címe. Áfás számla igénylésekor kötelező. | ||
customerNote | String | nem | Teljes rendeléshez tartozó megjegyzés. | |
deliveryAddress | Array | igen | Kötelező, ha kiszállítós rendelés. Amennyiben elviteles, akkor ezt az adatot nem kell megadni. | |
country | String | nem | Ország megjelölése ISO 3166 két karakteres változattal. | |
state | String | nem | Megye. | |
city | String | igen | Város. | |
zip | String | nem | Irányítószám. | |
address | String | igen | Utca teljes elnevezése. | |
number | String | igen | Házszám. | |
building | String | nem | Épület. | |
staircase | String | nem | Lépcsőház. | |
floor | String | nem | Emelet. | |
apartment | String | nem | Lakásszám. | |
intercom | String | nem | Csengő. | |
additional | String | nem | Egyéb megjegyzés a címhez. | |
position.lat | Double | nem | GPS koordináta. | |
position.lon | Double | nem | GPS koordináta. | |
billingAddress | Array | nem | Számlázási adatok | |
country | String | nem | Ország megjelölése ISO 3166 két karakteres változattal. | |
state | String | nem | Megye. | |
city | String | igen | Város. | |
zip | String | nem | Irányítószám. | |
address | String | igen | Utca teljes elnevezése. | |
number | String | igen | Házszám. | |
building | String | nem | Épület. | |
staircase | String | nem | Lépcsőház. | |
floor | String | nem | Emelet. | |
apartment | String | nem | Lakásszám. | |
intercom | String | nem | Csengő. | |
additional | String | nem | Egyéb megjegyzés a címhez. | |
position.lat | Double | nem | GPS koordináta. | |
position.lon | Double | nem | GPS koordináta. | |
vatNumber | String | igen | Adószám. | |
firstName | String | nem | Keresztnév. | |
lastName | String | nem | Vezetéknév. | |
companyName | String | nem | Cégnév. | |
itemsTotal | Double | igen | Összes termék árának kedvezményekkel csökkentett összege. | |
deliveryFee | Double | nem | Kiszállítási díj, ha van. | |
packagingFee | Double | nem | Csomagolási díj, ha van. | |
itemsDiscount | Double | nem | Rendelésre adott termék kedvezmények összege. Ellenőrzések: -nem lehet negatív szám -összege megegyezik a termékeknél adott kedvezményekkel | |
orderDiscount | Double | igen | Rendelésre adott fix összegű kedvezmény. | |
grandTotal | Double | igen | Végösszeg. | |
paidAmount | Double | igen | Már kifizetett összeg. Általában 0 (készpénzes, terminálos fizetésnél), vagy a grandTotallal megegyező lesz (teljes online fizetésnél). A futár [grandTotal - paidAmount] összeget fog kérni kiszállításkor. | |
orderAcceptedUrl | String | igen | Egy URL amit az Orsys rendszere meghív a rendelés elfogadásakor. | |
orderRejectedUrl | String | igen | Egy URL amit az Orsys rendszere meghív a rendelés elutasításakor. | |
orderPreparedUrl | String | nem | Egy URL amit az Orsys rendszere meghív a kért tételek elkészültekor (elviteles rendelésnél amikor átvehető az étel). Nem minden partner étteremnél fog helyes időpontot visszajelezni, mert azon múlik, hogy használják az éttermek a POS rendszert. | |
orderPickedUpUrl | String | nem | Egy URL amit az Orsys rendszere meghív a futár elindulásakor (vagy elviteles rendelésnél amikor átvették a rendelést). Nem minden partner étteremnél fog helyes időpontot visszajelezni, mert azon múlik, hogy használják az éttermek a POS rendszert. | |
orderItems | Array | igen | Rendelt termékek és tételek. Részletes magyarázat lentebb. |
A rendeléshez tartozó termékek felépítése.
Változó | Típus | Kötelező | Leírás |
---|---|---|---|
skuId | String | nem | Orsys-ban található termék azonosító. Nem kötelező de ajánlott elküldeni, hogy működjön az NTAK és a partner statisztikája. |
name | String | igen | Termék teljes elnevezése. Ez jelenik meg a POS felületen. |
note | String | nem | Termék megjegyzés. |
quantity | Int | nem | Rendelt mennyiség. |
discountUnitPrice | Double | nem | Termék kedvezményes egységára. Ha nincs kedvezmény akkor nem kell megadni. Ellenőrzések: -nem lehet negatív szám |
unitPrice | Double | igen | A termék egy db teljes ára. Nem tartalmazza a feltéteket és kedvezményeket. |
toppings | Array | nem | Termékhez tartozó rendelt feltétek. |
A termékekhez tartozó rendelt feltétek.
Változó | Típus | Kötelező | Leírás |
---|---|---|---|
skuId | String | nem | Orsys-ban található termék azonosító. |
name | String | igen | Termék teljes elnevezése. Ez jelenik meg a POS felületen. |
quantity | Int | nem | Rendelt mennyiség. |
discountUnitPrice | Double | nem | Egy egység kedvezményes ára. Ha nincs kedvezmény akkor nem kell megadni. Ellenőrzések: -nem lehet negatív szám |
unitPrice | Double | igen | Egy egység teljes ára, feltétekkel és kiegészítőkkel együtt. |
Csak a következő fizetési módokat lehet beküldeni:
A rendelés leadása után a következőt válaszolja a szerver.
Sikeres feldolgozás esetén 200-as státuszt add vissza a rendszer egy üres body-val.
Hiba esetén 400 Bad Request státuszt ad vissza és a body-ban található a hiba részletezése
Rendelés feldolgozás után a rendszer az alapján, hogy mit csinál az étterem, visszajelez a küldő félnek a megadott URL-eken.
A webhook esetén minden hívás body-ja azonos.
Kód | Leírás |
---|---|
ADDRESS_INCOMPLETE_MISSTATED | |
BAD_WEATHER | Rossz időjárás miatt nincs lehetőség a teljesítésre |
BLACKLISTED | A vásárló feketelistás, ezért nem lesz teljesítés |
CARD_READER_NOT_AVAILABLE | Az étterem jelenleg nem rendelkezik bankkártya terminállal |
CLOSED | Zárva az étterem |
CONTENT_WRONG_MISLEADING | A rendelés tartalma félrevezető, nem érthető |
FOOD_QUALITY_SPILLAGE | A vásárlónak problémája volt az étellel |
FRAUD_PRANK | Kamu vagy csaló rendelés |
ITEM_UNAVAILABLE | A rendelt tétel jelenleg nem elérhető |
LATE_DELIVERY | Késői kiszállítás miatt nem kérte a vásárló |
MENU_ACCOUNT_SETTINGS | Az étteremnek problémája van az átadott termékekkel |
MOV_NOT_REACHED | Túl alacsony rendelés érték miatt nem lesz teljesítve |
NO_COURIER | Nincs futár a kiszállítás elvégzésére |
NO_PICKER | Nincs elviteles rendelés |
NO_RESPONSE | Nincs válasz a rendelés feldolgozására |
OUTSIDE_DELIVERY_AREA | A kiszállítási területen kívűl található a rendelés |
TECHNICAL_PROBLEM | Technikai probléma miatt nem teljesíthető a rendelés |
TEST_ORDER | Teszt rendelés |
TOO_BUSY | Túl sok a rendelés miatt nem teljesíthető |
UNABLE_TO_FIND | Nem sikerült a vásárlót megtalálni és átadni a rendelést |
UNABLE_TO_PAY | A vásárló nem tudja kifizetni a rendelést |
UNPROFESSIONAL_BEHAVIOUR | Nem megfelelő viselkedés nem teljesíthető a rendelés |
WILL_NOT_WORK_WITH | Az étterem nem dolgozik ezzel a szolgáltatóval |
WRONG_ORDER_ITEMS_DELIVERED | Rossz termékek szállítása miatt nem kéri a vevő a rendelést |