Delivery Plugin integráció

Orsys rendelés integráció API dokumentáció

    Tesztelési hozzáférés

    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 összekötött szoftver vagy szolgáltatás neve,
    • Fejlesztő cég vagy magánszemély adatai,
    • Telefonos és e-mailes elérhetőségek.

    Autentikáció

    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.

    X-API-Key: "COPY API KEY HERE"

    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/delivery

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

    Részletes leírás az elemekre

    A teljes rendelés felépítése.

    VáltozóTípusKötelezőLeírás
    remoteIdStringigenÉttermen belüli egyedi rendelésazonosító
    cancelledBooleannemKorábban beküldött rendelés sztornózásakor legyen igaz. Ebben az esetben csak a remoteId-t kell tölteni, minden más lehet null.
    paymentTypeStringigenFizetési mód. Online fizetésnél állítani kell a paidAmount értéket is.
    scheduledTimeDateTimenemIdő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)
    takeAwayBooleannemElviteles rendelés esetén igaz értéket kell kapnia.
    customerArrayigenVásárló adatait tartalmazó vektor.
    nameStringigenVásárló teljes neve.
    phoneStringigenVásárló telefonszáma. Elvárt formátum: +36205230949
    emailStringnemVásárló e-mail címe. Áfás számla igénylésekor kötelező.
    customerNoteStringnemTeljes rendeléshez tartozó megjegyzés.
    deliveryAddressArrayigenKötelező, ha kiszállítós rendelés. Amennyiben elviteles, akkor ezt az adatot nem kell megadni.
    countryStringnemOrszág megjelölése ISO 3166 két karakteres változattal.
    stateStringnemMegye.
    cityStringigenVáros.
    zipStringnemIrányítószám.
    addressStringigenUtca teljes elnevezése.
    numberStringigenHázszám.
    buildingStringnemÉpület.
    staircaseStringnemLépcsőház.
    floorStringnemEmelet.
    apartmentStringnemLakásszám.
    intercomStringnemCsengő.
    additionalStringnemEgyéb megjegyzés a címhez.
    position.latDoublenemGPS koordináta.
    position.lonDoublenemGPS koordináta.
    billingAddressArraynemSzámlázási adatok
    countryStringnemOrszág megjelölése ISO 3166 két karakteres változattal.
    stateStringnemMegye.
    cityStringigenVáros.
    zipStringnemIrányítószám.
    addressStringigenUtca teljes elnevezése.
    numberStringigenHázszám.
    buildingStringnemÉpület.
    staircaseStringnemLépcsőház.
    floorStringnemEmelet.
    apartmentStringnemLakásszám.
    intercomStringnemCsengő.
    additionalStringnemEgyéb megjegyzés a címhez.
    position.latDoublenemGPS koordináta.
    position.lonDoublenemGPS koordináta.
    vatNumberStringigenAdószám.
    firstNameStringnemKeresztnév.
    lastNameStringnemVezetéknév.
    companyNameStringnemCégnév.
    itemsTotalDoubleigenÖsszes termék árának kedvezményekkel csökkentett összege.
    deliveryFeeDoublenemKiszállítási díj, ha van.
    packagingFeeDoublenemCsomagolási díj, ha van.
    depositFeesDictionarynemRendeléshez tartozó visszaváltási és betétdíjak. A kulcs az áfa érték az érték pedig a fizetendő összeg.
    itemsDiscountDoublenemRendelé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
    orderDiscountDoubleigenRendelésre adott fix összegű kedvezmény.
    grandTotalDoubleigenVégösszeg.
    paidAmountDoubleigenMá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.
    orderAcceptedUrlStringigenEgy URL amit az Orsys rendszere meghív a rendelés elfogadásakor.
    orderRejectedUrlStringigenEgy URL amit az Orsys rendszere meghív a rendelés elutasításakor.
    orderPreparedUrlStringnemEgy 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.
    orderPickedUpUrlStringnemEgy 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

    StringnemEgy 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.
    orderItemsArrayigenRendelt 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ípusKötelezőLeírás
    skuIdStringnemOrsys-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.
    nameStringigenTermék teljes elnevezése. Ez jelenik meg a POS felületen.
    noteStringnemTermék megjegyzés.
    quantityIntnemRendelt mennyiség.
    discountUnitPriceDoublenemTermék kedvezményes egységára. Ha nincs kedvezmény akkor nem kell megadni. Ellenőrzések:
    -nem lehet negatív szám
    unitPriceDoubleigenA termék egy db teljes ára. Nem tartalmazza a feltéteket és kedvezményeket.
    toppingsArraynemTermékhez tartozó rendelt feltétek.
    vatPercentDoublenemÁfa százalék (0/5/18/27), ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    ntakCategoryStringnemNTAK kategória, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    unitTypeStringnemMennyiségi egység, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    amountInUnitDoublenemMennyiség, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.

    Termék kiegészítők, feltétek

    A termékekhez tartozó rendelt feltétek.

    VáltozóTípusKötelezőLeírás
    skuIdStringnemOrsys-ban található termék azonosító.
    nameStringigenTermék teljes elnevezése. Ez jelenik meg a POS felületen.
    quantityIntnemRendelt mennyiség.
    discountUnitPriceDoublenemEgy egység kedvezményes ára. Ha nincs kedvezmény akkor nem kell megadni. Ellenőrzések:
    -nem lehet negatív szám
    unitPriceDoubleigenEgy egység teljes ára, feltétekkel és kiegészítőkkel együtt.
    vatPercentDoublenemÁfa százalék (0/5/18/27), ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    ntakCategoryStringnemNTAK kategória, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    unitTypeStringnemMennyiségi egység, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.
    amountInUnitDoublenemMennyiség, ha valamiért eltér az étlapon megadottól, vagy az skuId nincs megadva.

    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ódLeírás
    ADDRESS_INCOMPLETE_MISSTATED
    BAD_WEATHERRossz időjárás miatt nincs lehetőség a teljesítésre
    BLACKLISTEDA vásárló feketelistás, ezért nem lesz teljesítés
    CARD_READER_NOT_AVAILABLEAz étterem jelenleg nem rendelkezik bankkártya terminállal
    CLOSEDZárva az étterem
    CONTENT_WRONG_MISLEADINGA rendelés tartalma félrevezető, nem érthető
    FOOD_QUALITY_SPILLAGEA vásárlónak problémája volt az étellel
    FRAUD_PRANKKamu vagy csaló rendelés
    ITEM_UNAVAILABLEA rendelt tétel jelenleg nem elérhető
    LATE_DELIVERYKésői kiszállítás miatt nem kérte a vásárló
    MENU_ACCOUNT_SETTINGSAz étteremnek problémája van az átadott termékekkel
    MOV_NOT_REACHEDTúl alacsony rendelés érték miatt nem lesz teljesítve
    NO_COURIERNincs futár a kiszállítás elvégzésére
    NO_PICKERNincs elviteles rendelés
    NO_RESPONSENincs válasz a rendelés feldolgozására
    OUTSIDE_DELIVERY_AREAA kiszállítási területen kívűl található a rendelés
    TECHNICAL_PROBLEMTechnikai probléma miatt nem teljesíthető a rendelés
    TEST_ORDERTeszt rendelés
    TOO_BUSYTúl sok a rendelés miatt nem teljesíthető
    UNABLE_TO_FINDNem sikerült a vásárlót megtalálni és átadni a rendelést
    UNABLE_TO_PAYA vásárló nem tudja kifizetni a rendelést
    UNPROFESSIONAL_BEHAVIOURNem megfelelő viselkedés nem teljesíthető a rendelés
    WILL_NOT_WORK_WITHAz étterem nem dolgozik ezzel a szolgáltatóval
    WRONG_ORDER_ITEMS_DELIVEREDRossz termékek szállítása miatt nem kéri a vevő a rendelést