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#

  1. A Mergado Editorban kattints a jobb felső sarokban a profilodra, és nyisd meg az API és hozzáférések oldalt.
  2. 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.
  3. 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.
  4. 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#

  1. Nyisd meg a Mergado Marketplaces API dokumentációját.
  2. Kattints az Authorize gombra, és add meg a személyes hozzáférési tokenedet.
  3. 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:

  1. Rendszeres időközönként töltsd le a változásokat. A megrendelések listázásakor használd az updated_since paramé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.
  2. Importálás után jelöld meg a megrendelést. Mentsd el a rendszeredben lévő megrendelés-azonosítót. Az imported=false paraméterrel ezután csak a még nem importált megrendeléseket listázhatod.
  3. Í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.

Hasznos volt ez a cikk?