Ugrás a tartalomhoz

Az Agilix bolt integrációja az Allegróval

Hogyan használja az Agilix Sklep alkalmazás az Allegro REST API-t: célok, működés, hitelesítés, jogosultságok, adatok és a feltételeknek való megfelelés.

Állapot: 2026. október 1.

Az Agilix Sklep az Allegro Developer Apps rendszerben regisztrált alkalmazás, amely összeköti az agilix.dog webáruházat (játékok, jutalomfalatok és kiegészítők kutyáknak) egy Allegro eladói fiókkal. Ennek köszönhetően a boltnak egy termékkatalógusa, egy készlete és egy rendeléskezelése van - anélkül, hogy egy második háttérrendszert kellene vezetni az Allegro paneljében.

Az alkalmazást fejleszti és üzemelteti:

Hackerman Consulting - Adam Gajzlerowicz

NIP 7772841677

Regon 380997651

Hebanowa 16E, 62-020 Zalasewo, woj. wielkopolskie

+48 737 909 076

adam@agilix.dog

Az alkalmazás céljai

  • az agilix.dog bolt termékeinek meghirdetése ajánlatként az Allegrón, valamint nevük, leírásuk, fényképeik és áruk frissítése;
  • egyetlen közös készlet fenntartása - a boltban történő eladás csökkenti a darabszámot az Allegro-ajánlatban, az Allegrón történő eladás pedig a bolt készletét, általában egy percen belül;
  • az Allegro-rendelések letöltése a bolt rendeléskezelő paneljébe, hogy a boltban leadott rendelésekkel együtt lehessen teljesíteni őket;
  • a rendelés teljesítési állapotának és a küldemény számának továbbítása az Allegrónak.

Ki használja az alkalmazást

Az alkalmazást kizárólag az agilix.dog bolt adminisztrátora használja, a bolt beállításaiban, az adminisztrációs panelen. Egyetlen Allegro eladói fiókot kapcsol az alkalmazáshoz - azt, amelyről a bolt értékesít. A vásárlók és az Agilix többi felhasználója nem jelentkezik be ezen az alkalmazáson keresztül az Allegróba, és nem fér hozzá a beállításaihoz.

Hogyan működik az ajánlatok meghirdetése

Az adminisztrátor a terméknél bejelöli a "Meghirdetés az Allegrón" mezőt, kiválasztja a kategóriát, a kötelező paramétereket és az Allegrón érvényes árat. A termék mentése után az Agilix szervere a háttérben feltölti a fényképeket az Allegróra, létrehozza vagy frissíti az ajánlatot (termék, kategória és paraméterek, a gyártó és a felelős személy adatai a GPSR szerint, ár, darabszám, szállítási díjszabás, visszaküldési és reklamációs feltételek), majd közzéteszi.

  • A mező kijelölésének megszüntetése, a termék inaktiválása vagy a készlet elfogyása lezárja az ajánlatot; ha a termék újra elérhető, az ajánlat újraindul.
  • A módosítások a háttérben futó feladatsorba kerülnek, így a boltbeli szerkesztés nem vár az Allegro válaszára.
  • Ha az Allegro elutasítja az ajánlatot, az adminisztrátor a terméknél látja az Allegro hibakódját és üzenetét, és megismételheti a szinkronizálást.

Hogyan működik a rendelések kezelése

  • A szerver percenként egyszer beolvassa a rendelési események naplóját az utoljára feldolgozott eseménytől.
  • A rendelés csak akkor kerül a boltba, ha teljesítésre kész (READY_FOR_PROCESSING), és nem törölték; minden rendelés pontosan egyszer kerül importálásra, a készlet pedig a megrendelt darabszámmal csökken.
  • Ha a rendelést az Allegrón törlik, a boltban is törlődik, és a készlet visszaáll.
  • Amikor az adminisztrátor módosítja a rendelés állapotát vagy feladja a küldeményt, az alkalmazás frissíti a teljesítés állapotát az Allegrón, és hozzáadja a küldemény számát.
  • Az Allegro-rendelések visszatérítését az Allegro paneljében, az alkalmazáson kívül kezelik.

A felhasználó hitelesítése

Az alkalmazás az Allegro által biztosított szabványos OAuth 2.0 (Authorization Code) folyamatot használja. Senkitől sem kér felhasználónevet, jelszót, Client ID-t vagy Client Secretet.

  1. Az adminisztrátor a bolt beállításaiban az "Összekapcsolás az Allegróval" gombra kattint. A szerver létrehoz egy aláírt state paramétert, amely 15 percig érvényes, és ehhez az adminisztrátorhoz van kötve.
  2. A böngésző az Allegro bejelentkezési oldalára lép (https://allegro.pl/auth/oauth/authorize), ahol az eladó bejelentkezik a fiókjába, és hozzájárul az alkalmazás jogosultságaihoz.
  3. Az Allegro a regisztrált https://api.agilix.dog/allegro/oauth/callback címre irányít vissza. A szerver ellenőrzi a state aláírását és érvényességét, valamint azt, hogy a felhasználó továbbra is a bolt adminisztrátora, majd a kódot tokenekre cseréli (https://allegro.pl/auth/oauth/token), az alkalmazás saját Client ID-jával és Client Secretjével hitelesítve magát.
  4. A szerver beolvassa a csatlakoztatott fiók felhasználónevét, és elmenti a kapcsolatot. A frissítő token kizárólag a szerveren tárolódik, AES-256-GCM algoritmussal titkosítva. A hozzáférési token automatikusan frissül, az új frissítő token pedig azonnal felváltja az előzőt.

A Client Secret és a tokenek soha nem kerülnek a böngészőbe, a mobilalkalmazásba vagy más szereplőkhöz.

Az alkalmazás jogosultságai

Az alkalmazás csak a leírt funkciókhoz szükséges jogosultságokat kéri:

allegro:api:profile:read
a csatlakoztatott fiók felhasználónevének olvasása, hogy az adminisztrátor lássa, melyik Allegro-fiók van csatlakoztatva.
allegro:api:sale:offers:read
a bolt ajánlatainak és létrehozásuk eredményeinek olvasása, valamint a kategóriajavaslatok és a kategóriák paramétereinek olvasása.
allegro:api:sale:offers:write
a bolt ajánlatainak létrehozása, szerkesztése, közzététele és lezárása, valamint fényképeik feltöltése.
allegro:api:sale:settings:read
a szállítási díjszabások, a visszaküldési és reklamációs feltételek, valamint a gyártók és a felelős személyek adatainak (GPSR) olvasása, hogy az adminisztrátor kiválaszthassa őket az ajánlatokhoz.
allegro:api:sale:settings:write
a felelős gyártó adatainak (GPSR) hozzáadása, ha a fiókban még nincsenek meg.
allegro:api:orders:read
a rendelési események és részletek, a fuvarozók és a küldemények olvasása.
allegro:api:orders:write
a rendelés teljesítési állapotának frissítése és a küldemény számának hozzáadása.

A használt REST API-erőforrások

Minden kérést az Agilix szervere küld a https://api.allegro.pl címre (a fényképeket a https://upload.allegro.pl címre) a csatlakoztatott fiók nevében:

Ajánlatok és közzétételük

  • POST /sale/product-offers
  • PATCH /sale/product-offers/{offerId}
  • GET /sale/product-offers/{offerId}
  • GET /sale/product-offers/{offerId}/operations/{operationId}
  • GET /sale/offers
  • PUT /sale/offer-publication-commands/{commandId}
  • GET /sale/offer-publication-commands/{commandId}
  • GET /sale/offer-publication-commands/{commandId}/tasks

Fényképek

  • POST /sale/images

Kategóriák és paraméterek

  • GET /sale/matching-categories
  • GET /sale/categories/{categoryId}
  • GET /sale/categories/{categoryId}/parameters

Értékesítési beállítások

  • GET /sale/shipping-rates
  • GET /after-sales-service-conditions/return-policies
  • GET /after-sales-service-conditions/implied-warranties
  • GET /after-sales-service-conditions/warranties
  • GET /sale/responsible-producers
  • POST /sale/responsible-producers
  • GET /sale/responsible-persons

Rendelések

  • GET /order/events
  • GET /order/event-stats
  • GET /order/checkout-forms/{checkoutFormId}

Teljesítés és küldemények

  • PUT /order/checkout-forms/{checkoutFormId}/fulfillment
  • GET /order/checkout-forms/{checkoutFormId}/shipments
  • POST /order/checkout-forms/{checkoutFormId}/shipments
  • GET /order/carriers

Fiók

  • GET /me

Kezelt adatok

Az alkalmazás csak az értékesítéshez szükséges adatokat kezeli: a bolt ajánlatainak adatait és az Allegro-rendelések adatait - név, szállítási cím vagy átvételi pont, telefonszám, allegromail.pl domainű e-mail-cím, számlázási adatok, megrendelt termékek és az eladónak szóló üzenet.

A rendelési adatok kizárólag az adott rendelés teljesítésére és kiszállítására szolgálnak. A bolt nem küld az Allegro-vásárlóknak semmilyen e-mailt - sem tranzakciós, sem marketingcélút -, és adataikat nem használja marketingre.

A személyes adatok kezelésének szabályai: Adatvédelmi tájékoztató

Megfelelés az Allegro REST API feltételeinek

  • Az alkalmazás kizárólag a saját Client ID-ját és Client Secretjét használja, amelyeket szervertitokként tárol; senkivel sem osztja meg őket, és soha nem kéri a felhasználók kulcsait.
  • Az eladói fiókhoz csak OAuth 2.0-n keresztül fér hozzá, az eladó hozzájárulásával és a fent leírt jogosultságok keretein belül.
  • Minden kérés tartalmaz egy állandó, az alkalmazást azonosító User-Agent fejlécet: Agilix-Sklep/1.0.0 (+https://agilix.dog/).
  • Az alkalmazás betartja a korlátokat: a rendelési naplót percenként egyszer kérdezi le, az ajánlatokat csak a termék módosítása után frissíti, 429-es válasz után pedig annyit vár, amennyit a Retry-After fejléc jelez.
  • Nem tölti le tömegesen más eladók és vásárlók ajánlatait vagy adatait; az API-ból kapott adatokat kizárólag a csatlakoztatott fiók értékesítésének kezelésére használja.
  • A kommunikáció kizárólag HTTPS-en zajlik, a tokeneket titkosítva tárolja.

A fiók leválasztása

Az adminisztrátor bármikor a "Leválasztás" gombra kattinthat a bolt beállításaiban - a szerver ekkor törli a tárolt tokeneket és az ajánlatok kapcsolatait, az alkalmazás pedig nem küld több kérést ehhez a fiókhoz. A hozzáférés az Allegro oldalán, a fiók beállításaiban is visszavonható; az alkalmazás ekkor leválasztottként jelöli a kapcsolatot, és ezt megmutatja az adminisztrátornak.

Az alkalmazással kapcsolatos kérdések: adam@agilix.dog.