MPL API v2
MPL API v2
technikai leírás
Tartalomjegyzék
5. Kapcsolódás az MPL API-hoz 9
5.1 Általános Szerződési Feltételek 9
5.4 Sandbox(teszt) környezet 10
6.1.3 Átállás EFJ előállításáról MPL API használatára 11
6.2.2 Kérések csoportosítása 12
7.3 Csomagfeladás folyamata 16
7.4 HTTP Header információk 17
7.6 Üzleti szolgáltatás hívások 20
8. Nem funkcionális jellemzők 21
8.1.1 Szolgáltatási időszak 21
8.1.2 Karbantartási időszak 21
8.3 Nem támogatott JSON tag-ek 21
9. Gyakran Ismételt Kérdések 22
10. Melléklet – Adattípusok 23
11.1 Példa belföldi csomagok adatainak beküldésére 24
11.1.1 Csomag házhozszállítással 24
11.1.2 Csomag házhozszállítással,átutalásos árufizetéssel 25
11.1.3 Csomag PostaPontra szállítással, értéknyilvánítással 26
11.1.4 Csomag fix napi kézbesítéssel 27
11.1.5 Két csomagból álló szállítmány (együtt kézbesítendő) házhozszállítással, árufizetéssel, értéknyilvánítással 28
11.1.6 Csomag házhozszállítással, cserecsomaggal 29
11.1.7 Csomag házhozszállítással, és hozzá inverz címirat 31
11.1.8 Csomag csomagautomatára, könnyített kezeléssel, árufizetéssel, értéknyilvánítással 32 11.2 Példa nemzetközi csomagok adatainak beküldésére 33
11.2.1 EU-n kívüli csomag beküldése 33
11.2.2 EU-n belüli csomag beküldése 35
11.3 Csomagok feladásának zárása 36
1. Dokumentum
1.1 Rövidítések
Rövidítés | Magyarázat |
Base64 | A Base64 kódolás 64 karakterből álló ábécén alapuló tartalomkódolási forma, melynek segítségével bináris, illetve speciális karaktereket tartalmazó adatokból ASCII karaktersorozat állítható elő. |
HTTPS | Hypertext Transfer Protocol over SSL |
REST | Representational State Transfer |
URL | Uniform Resource Locator |
Táblázat 1 – Rövidítések
1.2 Fogalmak
Rövidítés | Magyarázat |
Csomag | Egy címzett számára szállítandó egyetlen küldemény. |
Szállítmány | Azonos címzett számára küldendő csomagok halmaza. Megkülönböztetünk együtt kezelendő (az összes csomag csak együtt kézbesíthető) és nem együtt kezelendő (a bele tartozó csomagok külön-külön is kézbesíthetők) szállítmányt. |
Jegyzék (EFJ) | A postai küldeményeket és az ügyfél adatokat tartalmazó adatállomány, mely az egy napon, egy helyen feladandó csomagok adatait tartalmazza. Lezárt jegyzék nélkül a csomagok adatait a posta nem tudja feldolgozni. |
Címirat | A csomagra ragasztandó címirat tartalmazza a feladó és vevő adatait, a csomag azonosítóját stb. |
Ragszám | A csomag azonosítója |
Táblázat 2 – Magyarázatok
1.3 Dokumentum történetiség
Verzió | Dátum | Megjegyzés |
1.0 | 2020.10.15 | Dokumentum létrehozása |
1.1 | 2020.10.19 | Apróbb pontosítások, EFJ generálásról API-ra való átállás részletezése |
2.0 | 2021.02.12 | Dokumentum redundancia megszüntetése, Devportal dokumentáció hivatkozás beszúrása |
2.1 | 2021.07.26. | Példák, új fejezet: 7.3 |
2.3 | 2021.10.15. | Pontosítások, új példák beillesztése |
Táblázat 3 – Dokumentum történetiség
2. Áttekintés
A Magyar Posta Zrt. MPL API web szolgáltatásokat nyújt, melyek lehetővé teszik a partnerei számára:
• szállítmányok létrehozását,
• szállítólevelek igénylését,
• csomagok címiratainak lekérdezését
• feladójegyzék lezárását
a céggel történő csomagszállítás céljából.
Az MPL API szolgáltatások használata díjmentes, bár az ügyfelek számára a saját kapcsolódó komponenseiknek a fejlesztései munkái költséggel járhatnak.
A Magyar Posta Zrt. nem vállal semmilyen felelősséget ezen fejlesztésekért, implementációkért és tesztelési költségekért.
Az alábbi hivatkozáson on-line dokumentáció található az MPL API üzleti hívásokról: xxxxx://xxxxxxxxx.xxxxx.xx/xxx/0
3. Dokumentum célja
A dokumentum az MPL API ügyfeleinek nyújt útmutatást és részletes leírást az MPL API REST webszolgáltatások integrációjához.
A dokumentum részletezi:
• A web szolgáltatás interfész specifikációt
• Az API által visszaadott hibakódokat
• Az API nem funkcionális leírását beleértve a szolgáltatás rendelkezésre állását és a biztonsági követelményeket
A dokumentáció elsősorban fejlesztőknek és rendszer integrátoroknak szól.
Az MPL API REST műveletek és HTTP metódusok, melyek ebben a dokumentumban kifejtésre kerülnek, az alábbiak:
• POST /oauth2/token
• GET /v2/mplapi/shipments
• POST /v2/mplapi/shipments
• POST /v2/mplapi/shipments/{trackingNumber}/item
• GET /v2/mplapi/shipments/{trackingNumber}
• DELETE /v2/mplapi/shipments/{trackingNumber}
• POST /v2/mplapi/shipments/close
• GET /v2/mplapi/shipments/label
• POST /v2/mplapi/addresses/cityToZipCode
• POST /v2/mplapi/addresses/zipCodeToCity
• POST /v2/mplapi/deliveryplace
• POST /v2/mplapi/reports
4. MPL API v2 bemutatása
4.1 Áttekintés
A legegyszerűbb esetben, a logikai folyamat az alábbi:
• Szállítmányok létrehozása – Tetszőleges számú szállítmány létrehozása, címiratok generálása
• Jegyzék zárása – Nap végén, de akár korábban is tetszőleges időpontban a feladójegyzék zárása, összesítő szállítólevél igénylése, mely egyben valamennyi, aktuálisan feladni kívánt küldemény adatát tartalmazza (kötelezően alkalmazandó funkció).
4.2 Interfész komponensek
Az 1-es képen látható az MPL API v2 és a hívó rendszer közötti interfész.
Kép 1 – MPL API v2
5. Kapcsolódás az MPL API-hoz
Az alábbi folyamatábrán látható a magas szintű folyamat leírása az MPL API-hoz kapcsolódási lépéseknek
Szerződés kötése
Kapcsolatfelvétel
Tesztelés Sandbox környezetben
DEVPORTAL
bejelentkezés
Éles környezeti hívások
Kép 2 – MPL API-hoz történő kapcsolódás folyamat
5.1 Általános Szerződési Feltételek
xxxxx://xxx.xxxxx.xx/xxxxxxxxxxxxxxx/xxxx/xxxxxx_xxxx
5.2 Devportal elérés
A Devportal-t éles környezetben az alábbi URL-en lehet elérni: xxxxx://xxxxxxxxx.xxxxx.xx
A Devportal-on bejelentkezés után lehet megtekinteni és kimásolni az API Sandbox és éles környezeti eléréshez szükséges API Key(client_id) és API Secret(client_secret) értékeket. A két környezetben
külön-külön bejelentkezési adatokat kell használni, ezek nem keverhetők a környezetek között.
5.3 API elérés
Az MPL API v2-t éles postai környezetben az alábbi root URL-eken lehet elérni: xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx
Az MPL API v2-t sandbox postai környezetben az alábbi root URL-eken lehet elérni: xxxxx://xxxxxxx.xxx.xxxxx.xx/x0/xxxxxx/
Az Authorization kulcs értéket minden egyes üzleti hívásban szerepeltetni kell, különben HTTP 401 (Unauthorized) hibaüzenetet kapunk válaszul.
5.4 Sandbox(teszt) környezet
Az Internetre publikált Sandbox (teszt) végpont mögött egy, az élessel megegyező alkalmazás és adatbázis található. Az eltérés annyi, hogy az adatbázisban található adatok nem feltétlenül
naprakészek (pl. postahelyek adataiban lehet eltérés), illetve ezeket az adatokat nem továbbítjuk a többi társrendszer felé.
5.5 Éles környezet
Az Internetre publikált éles végpont mögött az éles környezeti háttérszolgáltatás található.
5.6 API verziózás
A Magyar Posta Zrt. folyamatosan dolgozik a szolgáltatásai fejlesztésén, mely azt eredményezi, hogy az MPL API szolgáltatásokból új verzió kerül bevezetésre.
A Magyar Posta Zrt. 3 verziót tervez fenntartani az MPL API-ból:
• Aktuális verzió
• Előző verzió
• Érvénytelenített verzió
Mindig az aktuális verziójú MPL API szolgáltatáshoz kell kapcsolódni, ez biztosítja ugyanis a leghosszabb stabil időszakot, hogy a hívó rendszerben módosítani kellene. Ha az integrációt már elkezdte fejleszteni egy hívó rendszer, miközben új verzió került kiadásra az MPL API-ból, az előző verziót még használhatja a hívó rendszer.
Javasoljuk, hogy az érvénytelenített verzióval ne integrálja a hívó rendszerét.
6. Integrációs javaslatok
Az API hívások adatforgalmat és az MPL számára költségeket generálnak, ezért az MPL fenntartja a jogot, hogy extrém túlhasználat esetén az API szolgáltatás igénybevételét korlátozza.
Az optimális működés érdekében az MPL API integrációját az alábbiak figyelembevételével javasoljuk.
6.1 Üzleti
6.1.1 Címzés
Az MPL API figyelmeztetést ad vissza, ha a címzett címe lehet, hogy hibás, de a figyelmeztetés
ellenére elfogadja a beküldött adatokat. Javasoljuk, hogy ha van rá lehetőség, akkor ellenőrizzék a
címet és ha tényleg hibás volt, akkor töröljék a beküldött adatokat és a javított adatokkal újra küldjék be.
6.1.2 Szállítmánykezelés
A szállítmánykezelést az ÁSZF ismerteti minden pontra kiterjedően, itt csak röviden összefoglaljuk a közérthetőség kedvéért a lehetőségeket. Egy címre háromféleképpen adható fel csomag:
• Külön hívásban egyesével: a feladott csomagok teljesen függetlenek lesznek egymástól, nem kerülnek szállítmányba
• Egy szállítmányban beküldve nem együtt kezelendő módon: a feladott csomagok egy szállítmányban lesznek, amelyet azonban nem feltétlenül kézbesít egyszerre a posta
• Egy szállítmányban beküldve együtt kezelendő módon: a feladott csomagok egy szállítmányban lesznek, amelyet a posta egyszerre kézbesít
6.1.3 Átállás EFJ előállításáról MPL API használatára
Két fontos különbség van az EFJ helyi előállítása és MPL API között:
• Ragszám előállításának helye (EFJ esetén helyben történik, MPL API esetén a postánál)
• Adatok ellenőrzése MPL API-n azonnal megtörténik és hiba esetén nem is ad vissza ragszámot, azaz nem küldhető be hibás csomagadat
A csomagadatok beküldése után a címirat generálása történhet helyben is, ekkor a hívó fél felelőssége a megfelelő formátumú címirat előállítása. Ha megfelel az MPL API által visszaadott PDF formátumú címirat, akkor javasolt annak a használata.
6.1.4 Árak, zárás
A zárás híváskor az MPL API visszadja az adott jegyzékben szereplő ragszámokat és a hozzájuk tartozó árakat. Az árak a beküldött adatok alapján lettek meghatározva, ezért csak tájékoztató jellegűnek
tekinthetők, a tényleges feladás során kerülnek meghatározásra a pontos árak.
Fontos megjegyezni, hogy zárás esetén több jegyzék is készülhet függően a beküldött adatoktól.
6.2 Informatikai
MPL fenntartja a jogot, hogy a jövőben a hibás címzésű beküldött csomagokat visszautasítsa.
6.2.1 Csomagok életciklusa
Az MPL API-n beküldött csomagok a lezárásukig kezelhetők (törölhetők, generálható hozzájuk címirat stb). A lezárás után már csak címiratot lehet hozzájuk kérni (amíg archiválásra nem kerülnek).
6.2.2 Kérések csoportosítása
Amennyiben a hívó fél üzleti folyamata lehetővé teszi, úgy kérjük, hogy azon hívásokat, amelyeket
több adattal is meg lehet hívni (pl. szállítmányok beküldésekor vagy címiratkéréskor) lehetőleg több adat megadásával hívják meg, azaz egyszer száz adattal, ne százszor egy adattal.
A szállítmány beküldésekor azonnal kérhető címirat is. Amennyiben a hívó fél üzleti folyamatába
illeszkedik, úgy célszerű ezt egy lépésben megtenni és nem külön választani szállítmány beküldésére és külön címiratkérésre.
6.2.3 Adatcsomagok mérete
Néhány hívásnál limitációt vezettünk be az egyszerre beküldhető/lekérdezhető adatok számosságára. Ennek az indoka az, hogy a válaszok méretét limitáljuk, hiszen több hívás is PDF formátumú címiratot ad vissza base64 encode-oldva.
6.2.4 Hibakezelés
Az egyes szállítmányok adatainak beküldése után, ha az MPL API hibakódot ad vissza, akkor a hibás adato(ka)t javítani kell és ismételt módon be kell küldeni. A javításhoz használhatóak a hibakódok, ha valamilyen szinten automatizálni szeretnék a folyamatot. Ha a hibás eseteket minden esetben felhasználó döntésére bízzák, akkor elég számára a hibaüzenetet megjeleníteni.
7. MPL API szolgáltatások
Ez a fejezet leírja az MPL API v2 által nyújtott szolgáltatásokat, üzenet struktúrákat és mezőket, melyek a kérés és válasz üzenetben szerepelnek.
Ezek a műveletek elérhetőek Swagger specifikációban, melyet a Devportal--on tekinthet meg: xxxxx://xxxxxxxxx.xxxxx.xx/xxx/0
7.1 Üzleti szolgáltatások
MPL API v2 szállítmányok létrehozását / törlését / lekérdezését, címiratok lekérését, illetve a jegyzék zárását biztosítja partnerei számára.
Szolgáltatás | API művelet | Leírás | Technológia | Kapcsolat típusa |
Biztonság | ||||
OAuth2 token kérése | POST /oauth2/token | OAuth2 authorizá- ció esetén létrehoz egy authorizációs token-t, amit az üzleti hívások http fejlécében szerepeltetni kell | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Szállítmány | ||||
Szállítmány létrehozása | POST /v2/mplapi/shipments | Szállítmány létrehozása | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Szállítmányok címiratának lekérdezése | GET /v2/ mplapi/shipments/ label | Szállítmányok címiratának lekérdezése | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Szállítmány lekérdezése | GET /v2/ mplapi/shipments | Szállítmány lekérdezése | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Ragszám szerinti szállítmány lekérdezése | GET /v2/ mplapi/shipments/ {trackingNumber} | Szállítmány lekérdezése ragszám alapján | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Ragszám szerinti tétel törlése | DELETE /v2/ mplapi/shipments/ {trackingNumber} | Tétel törlése ragszám alapján | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Zárás | ||||
Jegyzék lezárása | POST /v2/ mplapi/shipments /close | Szállítmányok lezárása, elektronikus feladójegyzék és szállítólevél generálása | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Új csomagok felvétele | POST /v2/ mplapi/shipments/ {trackingNumber}/item | Új csomagok felvétele meglevő nem együtt kézbesítendő szállítmányba | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Irányítószámok lekérdezése | POST /v2/ mplapi/addresses/ cityToZipCode | Irányítószámok lekérdezése | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Település lekérdezése | POST /v2/ mplapi/addresses/ zipCodeToCity | Település lekérdezése | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Alternatív címzési pontok lekérdezése | POST /v2/ mplapi/deliveryplace | Alternatív címzési helyek lekérdezése (postapontok, postahelyek, csomagautomaták) | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Adatok lekérése | POST /v2/ mplapi/reports | Riportok lekérése (utalási, végállapot, függő küldemények) | JSON over HTTPS (REST) | Szinkron Kérés / Válasz |
Táblázat 4 – Üzleti szolgáltatások
7.2 Folyamat leírás
Authorizációs token kérése OAuth2 authorizáció esetén
Normál napi folyamat üzleti kérésekkel
7.3 Csomagfeladás folyamata
Függetlenül attól, hogy belföldi és/vagy nemzetközi csomagokat adnak fel, a csomagok adatainak beküldése végén ún. zárást kell végrehajtani. Enélkül a csomagok nem adhatók fel. A csomagadatok beküldhetők egyesével szekvenciálisan, egy kérésben több csomag egyszerre, illetve nagyobb
mennyiség esetén párhuzamosan is. Ez utóbbi esetben 5 szálnál többet ne használjanak a beküldés során.
MPL API | ||
ments | ||
ments | ||
ments | ||
ents/close | ||
Webshop
HTTP POST /ship
response HTTP POST /ship
response
HTTP POST /ship
response
...
HTTP POST /shipm
response
7.4 HTTP Header információk
7.4.1 Leírás
A HTTP header célja, hogy authentikációs, authorizációs biztonsági és logolási funkcionalitást biztosítson az MPL API rendszerben.
7.4.2 Kérés üzenet
Minden egyes üzleti hívást authorizálni kell Basic vagy OAuth2 authorizációval. Az ehhez szükséges client_id és client_secret értékeket az MPL API biztosítja. A mezők értékei elérhetőek az MPL API Developer portálon történő bejelentkezés után.
Paraméter | Opcionális | Leírás |
Authorization | Nem | Authorizációra szolgáló HTTP kulcs érték. Típusa és értéke az authorizációtól függően változik (OAuth2 vagy Basic) |
X-Accounting-Code | Nem | A Magyar Posta Zrt. által az ügyfél részére adott kód (vevőkód) Az MPL API a válasz üzenetbe beleteszi a hívó által beküldött X-Accounting-Code értékét. |
X-Request-ID | Nem | Üzenet egyedi azonosítója. Minden egyes MPL API hívás esetén egyedi GUID típusú értéke legyen a mezőnek. Pld: 827f3343-2cfd-4e46-a646-065a0a7268c4 Az MPL API ellenőrzi a GUID típus formátumát. Ha nem megfelelő a formátum, az üzenet elutasításra kerül. Az MPL API a válasz üzenetbe beleteszi a hívó által beküldött X-Request-ID értékét, így lehet összekötni a kérés és válasz üzenetet. |
X-Correlation-ID | Igen | Korrelált üzenet azonosítója GUID típussal. A logikailag összetartozó üzeneteknek ugyanaz legyen az azonosítójuk. Pld: F1A67AEF-70CE-42EB-B692-9C4CA81E1266 Az MPL API ellenőrzi a GUID típus formátumát. Ha nem megfelelő, az üzenet elutasításra kerül. Az MPL API a válasz üzenetbe beleteszi a hívó által beküldött X-Correlation-ID értékét. Ha a hívó rendszer nem adott meg X-Correlation-ID mezőt a kérésben, a válasz üzenetben sem fog szerepelni ez a mező. |
Táblázat 5 – HTTP fejléc információk az API kérésekben
OAuth2 authorizáció esetén authorizációs tokent kell igényelni a /oauth2/token művelet hívásával. A kapott tokent minden egyes üzleti hívás HTTP fejlécében szerepeltetni kell.
Basic authorizáció esetében a HTTP fejlécben a felhasználónév és jelszó párost base64 enkódolva kell megadni. A Basic authorizáció csak külön postai engedéllyel vehető igénybe!
7.4.3 Példa üzenet
Példa kérés a HTTP header-ben.
Bearer típusú kérést az OAuth2 authorizációs típus esetében kell szerepeltetni, Basic típusú kérést pedig a Basic authorizációs típus esetében
Paraméter | Érték |
Authorization | Bearer APRug5AE4VGAzNKDPAoxugLiDp0b |
Authorization | Basic Q2xpZW50SWRUaGF0Q2FuT25seVJlYWQ6c2VjcmV0MQ== |
Táblázat 6 – Példa HTTP fejléc értékek az API kérés üzenetben
7.5 OAuth2 token kérés
OAuth2 authorizáció használata esetében token-t kell kérni az üzleti hívások előtt.
7.5.1 Kérés üzenet
URL: xxxxx://xxxx.xxx.xxxxx.xx/xxxxx0/xxxxx
http művelet: POST
A kérést az alábbi módon kell megadni:
A HTTP header-ben egy szabványos Basic authentikáció kéréssel az Authorization key értéket kell megadni.
Pld: Authorization: Basic Q2xpZW50SWRUaGF0Q2FuT25seVJlYWQ6c2VjcmV0MQ==
• base64 enkódolt (API felhasználónév (API Key) : API account jelszó (API Secret)) az üzenet body-ban
• OAuth2 grant type key értéket kell megadni client_credentials value értékkel az üzenet body szekcióban
Paraméter | Hossz | Előfordulás | Adat típus | Leírás |
client_id | N/A | 1-1 | String | Kötelező. A felhasználónevet az MPL API biztosítja. |
client_secret | N/A | 1-1 | String | Kötelező. A jelszót az MPL API biztosítja. |
grant_type | N/A | 1-1 | String | Kötelező. Értéke: client_credentials Az üzenet Body szekcióban kell megadni. |
Táblázat 7 –Token kérés üzenet
A http header paraméterek között szerepeltetni kell a Content-Type:application/x-www-form-urlencoded paramétert az Authorization key érték mellett.
7.5.2 Válasz üzenet
A válasz üzenet body-ja tartalmazza az authorizációs token-t. A sikeres válasz esetében HTTP 200 (Ok) válasz kódot kapunk.
Mező | Max. hossz | Előfordulás | Adat típus | Leírás |
access_token | N/A | 1-1 | String | Authorizációs token |
expires_in | N/A | 1-1 | String | Token lejárata (másodpercben) 3600 másodperc |
Táblázat 8 –Token válasz üzenet releváns mezők
Az authorizációs token lejárata 3600 másodperc. Miután lejár az érvényessége, felhasználása után 401-es http kódot kapunk a válasz üzenetben. Ekkor új tokent kell igényelni a fenti leírt módon.
7.5.3 Példa üzenet
Token Kérés
grant_type=client_credentials
POST xxxx://xxxxxxxxx:00000/xxxxx0/xxxxx HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Q2xpZW50SWRUaGF0Q2FuT25seVJlYWQ6c2VjcmV0MQ==
Token Válasz
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "APRug5AE4VGAzNKDPAoxugLiDp0b", "issued_at": 1592910455065,
"expires_in": 1799, "token_type": "Bearer"
}
7.6 Üzleti szolgáltatás hívások
Az alábbi hivatkozáson található az MPL API v2 részletes leírása: xxxxx://xxxxxxxxx.xxxxx.xx/xxx/0
8. Nem funkcionális jellemzők
8.1 Rendelkezésre állás
8.1.1 Szolgáltatási időszak
Az MPL API elérhető a nap 24 órájában, az év 365 napján.
8.1.2 Karbantartási időszak
Az MPL API tervezett karbantartási időszaka az Általános Szerződési Feltételekben található.
8.1.3 Elérhetetlenség
Az MPL API v2 interfész elérhetelensége esetén a hívó rendszernek kell kezelni ezt a helyzetet.
8.2 Biztonság
Az összes MPL API művelet https prokollon keresztül hívható REST web service hívás.
Oauth2 authorizációt kell használni a műveletek hívásakor. Csak külön MPZRT által adott engedéllyel használható a Basic authorizáció.
8.3 Nem támogatott JSON tag-ek
Az MPL API figyelmen kívül hagyja a nem támogatott JSON tag-eket.
9. Gyakran Ismételt Kérdések
xxxxx://xxxxxxxxx.xxxxx.xx/xxx
10. Melléklet – Adattípusok
Az alábbi JSON adattípusok használhatók az MPL API v2 műveletekben: xxxxx://xxxxxxxxx.xxxxx.xx/xxx/0
11. Melléklet – Xxxxxx
Az MPL API ugyanazon végponton támogatja a belföldi és nemzetközi csomagok feladását is, így első ránézésre kicsit sok adat lehet szükséges. A dolgok megkönnyítése érdekében pár példát adunk
belföldi, illetve nemzetközi csomagok feladására is.
11.1 Példa belföldi csomagok adatainak beküldésére
11.1.1 Csomag házhozszállítással
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1212",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A4", "item": [
{
"weight": {
"value": "2560",
"unit": "g"
},
"services": {
"basic": "A_175_UZL", "extra": [], "deliveryMode": "HA"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr", "address": "Xxxxx xxxx 0"
}
},
"packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[{
"webshopId": "1", "trackingNumber": "PNAAA50069529",
"packageTrackingNumbers": ["PNAAA500695290019023000000"], "label": "JVBERi0xLjQKJeLjz9..."
}]
11.1.2 Csomag házhozszállítással, átutalásos árufizetéssel
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "10000319", "accountNo":"000000000000000000000000",
"contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1212",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "átutalásos"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A4", "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_ORZ","K_UVT","K_ENY"
],
"cod": "3000",
"value": "3000", "deliveryMode": "HA"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "törékeny"
}
},
"paymentMode": "UV_AT", "packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[{
"webshopId": "1", "trackingNumber": "PKAAA50058206",
"packageTrackingNumbers": ["PKAAA500582060011138001500"], "label": "JVBERi0xLjQKJeLjz9..."
}]
11.1.3 Csomag PostaPontra szállítással, értéknyilvánítással
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1215",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "készpénzes"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A5", "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_ENY"
],
"value": "3000", "deliveryMode": "PP"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "MOL kútra",
"parcelPickupSite":"12063 sz. MOL töltőállomás"
}
},
"paymentMode": "UV_KP", "packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[{
"webshopId": "1", "trackingNumber": "PNAAA50000034",
"packageTrackingNumbers": ["PNAAA500000340017101000000"], "label": "JVBERi0xLjQK..."
}]
11.1.4 Csomag fix napi kézbesítéssel
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1212",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A4", "deliveryDate":"2021-09-28", "item": [
{
"weight": {
"value": "2560",
"unit": "g"
},
"services": {
"basic": "A_175_UZL", "extra": ["K_FNK"], "deliveryMode": "HA"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr", "address": "Xxxxx xxxx 0"
}
},
"packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[{
"webshopId": "1", "trackingNumber": "PNAAA50069532",
"packageTrackingNumbers": ["PNAAA500695320019023000000"], "label": "JVBERi0xLjQKJeLjz9..."
}]
11.1.5 Két csomagból álló szállítmány (együtt kézbesítendő) házhozszállítással, árufizetéssel, értéknyilvánítással
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1215",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "készpénzes"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A5", "groupTogether":true, "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L",
"services": {
"basic": "A_175_UZL", "extra": [
"K_ORZ","K_UVT","K_ENY"
],
"cod": "3000",
"value": "3000", "deliveryMode": "HA"
}
},
{
"weight": {
"value": "1001",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_ORZ","K_UVT","K_ENY"
],
"cod": "4000",
"value": "4000", "deliveryMode": "HA"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "törékeny"
}
},
"paymentMode": "UV_KP", "packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[{
"webshopId": "1", "trackingNumber": "PKQZ050115785",
"packageTrackingNumbers": ["PKQZ0501157850021138000000",…], "label": "JVBERi0..."
}]
11.1.6 Csomag házhozszállítással, cserecsomaggal
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Xxxxxx Xxxxx",
"email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1215",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "készpénzes"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A5", "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_CSE"
],
"deliveryMode": "HA"
},
"replacementPackage": {
"customData1": "cserecsomag", "customData2": "visszaküldendő", "extra": ["K_ENY"],
"weight": {
"value": "2000",
"unit": "G"
},
"value":"1000"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "törékeny",
}
},
"paymentMode": "UV_KP", "packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[
{
"webshopId": "1", "trackingNumber": "PNBBZ50000092",
"replacementTrackingNumber": "PIBBZ50000106", "replacementLabels": [
{
"trackingNumber": "PIBBZ50000106", "label": "JVBERi0xLjQKJ…"
}]
11.1.7 Csomag házhozszállítással, és hozzá inverz címirat
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1215",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "készpénzes"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A4", "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_INV"
],
"deliveryMode": "HA"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília", "email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "törékeny",
}
},
"paymentMode": "UV_KP", "packageRetention": "0"
}
]
A kéréshez tartozó válasz:
[
{
"webshopId": "1", "trackingNumber": "PIBBZ50000119", "packageTrackingNumbers": [
"PIBBZ500001190019023000000"
],
"label": "JVBERi0xLjQKJ…"
}]
11.1.8 Csomag csomagautomatára, könnyített kezeléssel, árufizetéssel, értéknyilvánítással
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[
{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Flóra", "email": "xxxxxx@xxxxx.xxx", "phone":"x000-0000000"
},
"address": {
"postCode": "1215",
"city": "Budapest",
"address": "Xxxxx Xxxxxx xx 0", "remark": "készpénzes"
}
},
"orderId": "0014", "developer": "AAA Kft", "webshopId": "1",
"labelType": "A4", "item": [
{
"customData1": "ügyféladat1", "customData2": "ügyféladat2", "weight": {
"value": "2560",
"unit": "g"
},
"size": "L", "services": {
"basic": "A_175_UZL", "extra": [
"K_UVT","K_ENY"
],
"cod": "3000",
"value": "3000", "deliveryMode": "CS"
}
}
],
"recipient": {
"contact": {
"name": "Címzett Cecília",
"email": "xxxxx@xxxxx.xxx", "phone": "x0000-0000000"
},
"address": {
"postCode": "9023",
"city": "Győr",
"address": "Xxxxx xxxx 0", "remark": "törékeny",
"parcelPickupSite":"20 sz. automata - Tatabánya 1 posta"
},
"disabled": true
},
"paymentMode": "UV_KP", "packageRetention": "10"
}
]
A kéréshez tartozó válasz:
[
{
"webshopId": "1", "trackingNumber": "PKBBZ50000122", "packageTrackingNumbers": [
"PKBBZ500001220012801003000"
],
"label": "JVBERi0xLjQKJ…"
}]
11.2 Példa nemzetközi csomagok adatainak beküldésére
11.2.1 EU-n kívüli csomag beküldése
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Árvíztűrő Tükörfúrógép", "email": "xxxxxx.xxxxxxxxx@xxxxx.xx", "phone": "x0000-0000000",
"organization": "Küldő Cég Árvíztűrő Tükörfúrógép"
},
"address": {
"postCode": "1111",
"city": "Budapest", "address": "Xxxxx xxxx 0",
"remark": "Feladó megjegyzése Árvíztűrő tükörfúrógép", "countryCode": "HU"
},
"accountNo":"22222222-22222222",
},
"orderId": "2400", "developer": "AAA Kft", "webshopId": "3600",
"item": [{
"customData1": "Ügyféladat Egy", "customData2": "Ügyféladat Kettő",
"weight": {
"value": 12002, "unit": "G"
},
"size": "", "services": {
"basic": "A_121_CSG", "extra": ["K_ENY","K_UVT"], "cod": 999,
"value": 653, "deliveryMode": "HA", "codCurrency": "EUR", "customsValue": 198,
"otherComment": "Általános megjegyzés", "customsValueCurrency": "EUR", "produceContent": "11",
"DescriptionOfGoods": 32
},
"ewcCode": "150101",
"documents": [{
"authorisationNr": "PSZ12345", "name": "325 Proforma számla"
}, {
}, {
}, {
}, {
}, {
}],
"authorisationNr": "PSZ88006600", "name": "325 Proforma számla"
"authorisationNr": "KE1234567", "name": "811 Kiviteli engedély"
"authorisationNr": "KE100000", "name": "811 Kiviteli engedély"
"authorisationNr": "SZT9876543", "name": "861 Származási tanúsítvány"
"authorisationNr": "XXX000000", "name": "861 Származási tanúsítvány"
"customs": [{
"produceCount": 3,
"produceName": "Csomag 1",
"produceValue": 10,
"tariffCode": "987654", "country": "HU", "weightValue": 1234,
"value": 0
},
{
"produceCount": 5,
"produceName": "Csomag 2",
"produceValue": 22,
"tariffCode": "98765432", "country": "CZ", "weightValue": 1200,
"value": 0
},
{
"produceCount": 2,
"produceName": "Csomag 3",
"produceValue": 8,
"tariffCode": "9876543210", "country": "AT", "weightValue": 850,
"value": 0
},
{
"produceCount": 6,
"produceName": "Csomag 4",
"produceValue": 7,
"tariffCode": "1020304050", "country": "TR", "weightValue": 100,
"value": 0
}],
}
],
"recipient": {
"contact": {
"name": "AYVALIK BALIKESİR",
"email": "xxxxxxx.xxxxxxxxx@xxxxx.xxx", "phone": "x000000000000",
"organization": "Egy Török Cég Árvíztűrő Tükörfúrógép"
},
"address": {
"postCode": "43502",
"city": "Antalya",
"address": "AKSU S XXXX X X 00/0, Xxxxxxx", "remark": "Nem jó a csengő, dudáljon már a futár", "countryCode": "TR"
},
},
"paymentMode": "UV_AT", "packageRetention": 5
}]
A kéréshez tartozó válasz:
[{
"webshopId": "3600", "trackingNumber": "CC900105354HU",
"packageTrackingNumbers": ["CC900105354HU"], "label": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8..."
}]
11.2.2 EU-n belüli csomag beküldése
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx címre:
[{
"sender": {
"agreement": "00000000", "contact": {
"name": "Feladó Árvíztűrő Tükörfúrógép", "email": "xxxxxx.xxxxxxxxx@xxxxx.xx", "phone": "x0000-0000000",
"organization": "Küldő Cég Árvíztűrő Tükörfúrógép"
},
"address": {
"postCode": "1111",
"city": "Budapest", "address": "Xxxxx xxxx 0",
"remark": "Feladó megjegyzése Árvíztűrő tükörfúrógép", "countryCode": "HU"
},
"accountNo":"22222222-22222222",
},
"orderId": "2400", "developer": "AAA Kft",
"webshopId": "3600",
"item": [{
"customData1": "Ügyféladat Egy", "customData2": "Ügyféladat Kettő", "weight": {
"value": 12002, "unit": "G"
},
"size": "", "services": {
"basic": "A_125_HAR", "extra": ["K_TER"], "deliveryMode": "HA", "customsValue": 0,
"otherComment": "Általános megjegyzés", "customsValueCurrency": "EUR", "produceContent": "11",
"DescriptionOfGoods": 32
},
"ewcCode": "150101",
}
],
"recipient": {
"contact": {
"name": "Xxxxxx Xxxxxxx",
"email": "xxxxxx.xxxxxxx@xxxxx.xxx", "phone": "x000000000000",
"organization": "Osztrák Cég Árvíztűrő Tükörfúrógép"
},
"address": {
"postCode": "B318",
"city": "Vienna",
"address": "Xxxxxxxxxxxxxx 00",
"remark": "Nem jó a csengő, dudáljon a futár", "countryCode": "AT"
},
},
"paymentMode": "UV_AT", "packageRetention": 5
}]
A kéréshez tartozó válasz:
[{
"webshopId": "3600",
"trackingNumber": "JJH30AAAAAAT90032420", "packageTrackingNumbers": ["JJH30AAAAAAT90032420"], "label": "JVBERi0xLjQKJ..."
}]
11.3 Csomagok feladásának zárása
HTTP POST a xxxxx://xxxx.xxx.xxxxx.xx/x0/xxxxxx/xxxxxxxxx/xxxxx címre:
{
"checkList": true, "checkListWithPrice": true,
}
A kéréshez tartozó válasz:
[{
"manifest": "JVBERi0xL...", "trackingNrPrices": [ {
"trackingNumber": "PNQZ0501157850011138000000",
"price": 1250
}]
}]