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
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.
- Az adminisztrátor a bolt beállításaiban az "Összekapcsolás az Allegróval" gombra kattint. A szerver létrehoz egy aláírt
stateparamétert, amely 15 percig érvényes, és ehhez az adminisztrátorhoz van kötve. - 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. - Az Allegro a regisztrált
https://api.agilix.dog/allegro/oauth/callbackcímre irányít vissza. A szerver ellenőrzi astatealáí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. - 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
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.
