Saját rendelésintegráció a Mergado Marketplaces API-n keresztül#
A Mergado Marketplaces kész megrendelés-integrációkat kínál olyan rendszerekhez, mint a POHODA, Shoptet Premium, WooCommerce, UNAS vagy Upgates. Ha a megrendeléseidet más rendszerben kezeled — például saját ERP-ben, raktárkezelő szoftverben vagy belső alkalmazásban —, akkor a Mergado Marketplaces API segítségével saját magad is csatlakoztathatod azokat. Ehhez csak egy fejlesztőre van szükséged, aki az integrációt a rendszered oldalán megprogramozza.
Az API-n keresztül:
- letöltheted a megrendeléseket a Mergado Marketplaces-hez csatlakoztatott összes marketplace-ről (Allegro, Kaufland, Amazon), beleértve a CSV exportban szereplő összes adatot: vásárló adatai, számlázási és szállítási cím, fizetés, szállítás, megrendelés tételei, dokumentumok és megjegyzések,
- megrendeléseket importáltként jelölhetsz meg a rendszeredben lévő azonosítójuk megadásával — a következő letöltéskor így csak az új megrendeléseket kapod meg,
- megváltoztathatod a megrendelés státuszát, beleértve a csomagszámot és a futárt. A változtatás közvetlenül az Allegrora vagy a Kauflandra kerül,
- számlát tölthetsz fel az Allegrón vagy Kauflandon lévő megrendeléshez.
A teljes technikai dokumentáció a Mergado Marketplaces API dokumentációjában található. Az összes végpontot, paramétereiket és a válaszok formátumát megtalálod benne. A hívásokat közvetlenül a saját adataidon is kipróbálhatod.
📝 Érdemes tudni:
- Az API dokumentációja és a hibaüzenetek angolul jelennek meg.
- Az API fejlesztőknek szól. Ha programozás nélkül szeretnéd csatlakoztatni a megrendeléseket, nézd meg, hogy a rendszered megtalálható-e a Mergado Marketplaces kész integrációi között.
Amire szükséged lesz#
- Aktív Mergado Marketplaces bővítmény legalább egy csatlakoztatott marketplace-szel.
- Személyes hozzáférési token (PAT) a Mergado fiókodból Webáruház adatainak olvasása jogosultsággal.
- A Mergado-ban lévő webáruház azonosítója.
- Fejlesztő, aki az integrációt a rendszeredben megprogramozza.
⚠️ Használd vagy az API-t, vagy a kész webáruház-integrációt — egyszerre ne mindkettőt. Ha a Mergado Marketplaces-ben aktív megrendelés-integráció van beállítva egy e-kereskedelmi platformhoz (például Shoptet Premium, Upgates vagy WooCommerce), és ugyanazokat a megrendeléseket API-n keresztül is feldolgozod, a két rendszer felülírhatja egymás rendelési státuszait.
Az integráció beállítása#
1. Hozz létre személyes hozzáférési tokent#
- A Mergado Editorban kattints a jobb felső sarokban a profilodra, és nyisd meg az API és hozzáférések oldalt.
- Kattints a + Token létrehozása gombra, adj nevet a tokennek (például „Megrendelések integrációja ERP-be"), és állítsd be az érvényességi időt.
- A jogosultságoknál a Webáruház csoportban jelöld be a Webáruház adatainak olvasása opciót. A Mergado Marketplaces API-nak más jogosultságra nincs szüksége.
- Hozd létre a tokent, másold ki és tárold biztonságosan. Az oldal elhagyása után már nem lesz megjeleníthető.
A részletes eljárást a Személyes hozzáférési token (PAT) cikkben találod.
⚠️ Ne keverje össze a Webáruház adatainak olvasása (Webáruház csoport) jogosultságot a Felhasználó webáruházainak olvasása (Felhasználó csoport) jogosultsággal. A Mergado Marketplaces API az előbbire van szüksége.
A token ugyanazokhoz a webáruházakhoz fér hozzá, mint a fiókod. A megrendelések olvasásához elegendő olvasási hozzáférés a webáruházhoz. A megrendelés státuszának módosításához, számla feltöltéséhez vagy saját megrendelés-azonosító megadásához írási hozzáférés szükséges.
2. Keresd meg a webáruházad azonosítóját#
Minden API-hívás tartalmazza a webáruház numerikus azonosítóját a Mergadóban. Ezt a legegyszerűbben az API és hozzáférések beállításaiban kapcsolhatod be: engedélyezd a belső azonosítók megjelenítését. A webáruház azonosítója ekkor zárójelben jelenik meg a neve mellett. A lépéseket a Belső entitásazonosítók megjelenítéséről cikk írja le.
3. Próbáld ki az API-t a dokumentációban#
- Nyisd meg a Mergado Marketplaces API dokumentációját.
- Kattints az Authorize gombra, és add meg a személyes hozzáférési tokenedet.
- Válassz például egy megrendelés-listázó végpontot, add meg a webáruház azonosítóját, majd kattints a Try it out, majd az Execute gombra.
A dokumentáció megmutatja a valódi választ a megrendelési adataiddal és a pontos kérési URL-t, amelyet a fejlesztőd közvetlenül felhasználhat.
4. Csatlakoztasd a rendszeredet#
Az összes hívás a Mergado API-n keresztül megy a https://api.mergado.com/apps/ordelogyproducts/proxy címen. A tokent az Authorization: Bearer <a te tokened> fejlécben kell elküldeni. A konkrét végpontokat és paramétereket a fejlesztőd a dokumentációban találja.
Ajánlott megrendelés-szinkronizációs folyamat#
A megrendelések rendszeres átvételéhez a következő megközelítést ajánljuk:
- Rendszeres időközönként töltsd le a változásokat. A megrendelések listázásakor használd az
updated_sinceparamétert az utolsó letöltés időpontjával. Megkapod az új megrendeléseket és azokat is, amelyek azóta bármilyen szempontból megváltoztak — például státusz, adatok, szinkronizációs hiba vagy feltöltött számla. - Importálás után jelöld meg a megrendelést. Mentsd el a rendszeredben lévő megrendelés-azonosítót. Az
imported=falseparaméterrel ezután csak a még nem importált megrendeléseket listázhatod. - Írd vissza a változtatásokat. Amikor a rendszeredben feladod a megrendelést, küld el az API-n keresztül a SENT státuszt a csomagszámmal együtt. A változtatás közvetlenül a marketplace-re kerül. Ugyanígy tölthetsz fel számlát is.
Az időzóna nélküli időpontokat az API közép-európai időként (Europe/Prague) értelmezi. A válaszokban szereplő összes időpont ugyanebben az időzónában van.
Megrendelés-státuszok#
A Mergado Marketplaces az egyes marketplace-ek státuszait egységes státuszokra képezi le. Az API-ban ezek a következőképpen jelennek meg:
| API-státusz | Státusz a Mergado Marketplaces-ben |
|---|---|
OPEN |
nyitva |
READY |
elküldetlen |
PROCESSING |
feldolgozás alatt |
SENT |
elküldve |
ONHOLD |
felfüggesztve |
RETURNED |
visszaküldve |
CANCELLED |
törölve |
UNKNOWN |
ismeretlen |
Az API-n keresztül az alábbi státuszok állíthatók be:
| Marketplace | Beállítható státuszok |
|---|---|
| Allegro | PROCESSING, SENT, CANCELLED, ONHOLD |
| Kaufland | PROCESSING, SENT, CANCELLED |
Az Amazon esetén a megrendelések az API-n keresztül csak olvashatók.
A Mergado Marketplaces-ben lévő státusz csak akkor frissül, ha a marketplace elfogadja. Ha elutasítja, az API visszaad egy hibát a marketplace indoklásával, és a hiba a megrendelésnél is megjelenik a Mergado Marketplaces-ben. A sikertelen módosítás nem ismétlődik meg automatikusan. Olyan státuszt is elküldhetsz, amellyel a megrendelés már rendelkezik — például ha egy már elküldöttként megjelölt megrendeléshez utólag szeretnéd hozzáadni a csomagszámot.
Számlák#
Az Allegrón vagy Kauflandon lévő megrendeléshez az API-n keresztül legfeljebb 5 MB méretű PDF-számlát tölthetsz fel a számlaszámmal együtt. A feltöltés eredménye a Mergado Marketplaces megrendelési előzményeiben látható.
Korlátok#
- Egyetlen IP-címről legfeljebb 60 kérés percenként küldhető.
- Egy hívás legfeljebb 1 000 megrendelést ad vissza. A további megrendelések lapozással tölthetők be.
GYIK#
Szükséges-e valamilyen speciális csatlakoztatás a Mergado Marketplaces-ben az API használatához?#
Nem. Csak egy személyes hozzáférési tokenre és a webáruház azonosítójára van szükséged. A Csatlakozások szekcióban csak ellenőrizd, hogy a marketplace-eknél engedélyezve van-e a megrendelések szinkronizációja. Az API-hoz semmi mást nem kell beállítani.
Az API 403-as hibát ad vissza: „Missing required scope: shop.read". Mit tegyek?#
A tokennek nincs Webáruház adatainak olvasása jogosultsága. Hozz létre új tokent, és a Webáruház csoportban jelöld be ezt a jogosultságot.
Az API 403-as hibát ad vissza: „Access denied for this eshop". Mit tegyek?#
A fiókodnak nincs megfelelő hozzáférése a webáruházhoz, vagy a webáruház azonosítója nem egyezik. Ellenőrizd a webáruház azonosítóját és a hozzáférési jogosultságaidat. A státusz módosításához, számla feltöltéséhez és megrendelés-azonosító írásához írási hozzáférés szükséges. Az újonnan megadott hozzáférés akár 5 percet is igénybe vehet.
Az API 401-es hibát ad vissza. Mit tegyek?#
A kérés nem tartalmaz tokent, vagy a token érvénytelen. Ellenőrizd, hogy a teljes tokent az Authorization fejlécben küldöd-e, és hogy nem járt-e le, illetve nem vonták-e vissza.
Miért hiányoznak a régebbi megrendelések státuszváltozásai, ha dátum szerint töltök le?#
A date_from és date_to paraméterek a megrendelés leadásának dátuma szerint szűrnek. Nem rögzítik a régebbi megrendelések státuszváltozásait, például a lemondásokat. A rendszeres szinkronizációhoz az updated_since paramétert használd.
Használhatom az API-t egy webáruház-platform integrációval párhuzamosan?#
Nem ajánljuk. Ha a megrendeléseket egyidejűleg dolgozza fel egy webáruház-integráció (például Shoptet Premium vagy Upgates) és a saját rendszered az API-n keresztül, felülírhatják egymás megrendelési státuszait. A megrendelések átviteléhez vagy az API-t, vagy a kész integrációt használd.
Dolgozhatok több webáruházzal az API-n keresztül?#
Igen. A token minden olyan webáruházhoz hozzáfér, amelyhez a Mergado fiókod hozzáféréssel rendelkezik. Minden hívásban megadod annak a webáruháznak az azonosítóját, amellyel dolgozni szeretnél.
Segítetek-e az integrációban?#
Magát az integrációt a fejlesztőd programozza a dokumentáció alapján. Ha az integráció során problémába ütközöl, vagy az API-ból hiányzik egy szükséges adat, írj a Mergado ügyfélszolgálatának.