Plugin API

Rendelés átadás

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.

1{
2	"remoteId": "22636",
3	"paymentType": "CASH",
4	"scheduledTime": "2023-09-13T18:17:30+02:00",
5	"takeAway": false,
6	"customer": {
7		"name": "Nagy Árpád",
8		"phone": "+36201234567",
9		"email": "nagy.arpad@mintaemail.hu"
10	},
11	"customerNote": "Kérem csörögjön a futár ha itt van.",
12	"deliveryAddress": {
13		"zip": "1101",
14		"city": "Budapest",
15		"address": "Mongol utca",
16		"number": "75",
17		"building": "B",
18		"staircase": "",
19		"floor": "4",
20		"apartment": "23",
21		"intercom": "Nagy Árpád, 23",
22		"additional": "Piros ajtó a lifttől balra",
23		"position": {
24			"lat": 47.4713559,
25			"lon": 19.1310685
26		}
27	},
28	"itemsTotal": 6590,
29	"deliveryFee": 500,
30	"packagingFee": 300,
31	"itemsDiscount": 0,
32	"orderDiscount": 1000,
33	"grandTotal": 6390,
34	"paidAmount": 0,
35	"orderAcceptedUrl": "https://ipn.sajatdomain.hu/success/22636",
36	"orderRejectedUrl": "https://ipn.sajatdomain.hu/storno/22636",
37	"orderItems": [
38		{
39			"skuId": "AAA-011",
40			"name": "Jalapenos pizza (32 cm)",
41			"quantity": 2,
42			"unitPrice": 2100,
43			"note": "",
44			"toppings": [
45				{
46					"skuId": "AAR-002",
47					"name": "Bacon",
48					"quantity": 1,
49					"unitPrice": 300
50				},
51				{
52					"skuId": "AAR-006",
53					"name": "Feta sajt",
54					"quantity": 1,
55					"unitPrice": 250
56				}
57			]
58		},
59		{
60			"skuId": "AAZ-001",
61			"name": "Sajtburger",
62			"quantity": 1,
63			"unitPrice": 1290,
64			"note": "Kérem a húst jól süssék át."
65		}
66	]
67}

Részletes leírás az elemekre

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
	email	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. Nem minden partner étteremnél fog helyes időpontot visszajelezni, mert azon múlik, hogy használják az éttermek a POS rendszert.
orderCompletedUrl		String	nem	Egy URL amit az Orsys rendszere meghív a rendelés teljesítésekor (elviteles rendelésnél is). 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.

Rendelt termékek

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.

Termék kiegészítők, 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.

Választható fizetési módok

Csak a következő fizetési módokat lehet beküldeni:

CASH - Készpénz
CASH_EUR - Készpénz Euró
CASH_LARGE_BILLS - Készpénz nagy címlet
SZEP_CARD_ONLINE - SZÉP kártyás fizetés online teljesítve
SZEP_CARD_TERMINAL - SZÉP kártyás fizetés futárnál
CREDIT_CARD_ONLINE - Bankkártyás fizetés online teljesítve
CREDIT_CARD_TERMINAL -Bankkártyás fizetés futárnál
VOUCHER - Utalvány

Válasz a szerverről

A rendelés leadása után a következőt válaszolja a szerver.

Sikeres feldolgozás esetén

Sikeres feldolgozás esetén 200-as státuszt add vissza a rendszer egy üres body-val.

Hiba esetén

Hiba esetén 400 Bad Request státuszt ad vissza és a body-ban található a hiba részletezése

1{
2	"exceptionMessage": "exc_invalid_field",
3	"additionalInfo": "Missing remoteId!"
4}

Visszajelzés

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.

TESZT RENDSZER ESETÉN: a teszt rendszerben automatikus visszajelzés történik a rendelés beérkezése után 60 másodperccel. A visszajelzés random, 50-50 %-ban sikeres és sikertelen. Ez csak azért van, hogy könnyedén le tudjátok tesztelni a visszajelzés részt is.

A webhook esetén minden hívás body-ja azonos.

1{
2	"remoteId": "22360",
3	"status": "ACCEPTED",
4	"acceptanceTime": "2023-09-13T18:17:30+02:00",
5	"rejectReason": Null
6}

Elutasítási indokok

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

Plugin integráció

Tesztelési hozzáférés

Autentikáció