API-kulcsok és jogosultságok
API-kulcs létrehozása fő fiókhoz vagy alfiókhoz, a választható jogosultságok, a kulcs láthatósága, használata és visszavonása.
This article is currently available in Hungarian only.
Az API-kulcs azonosítja a rendszeredet a REST API-ban. Minden kulcs egy fiókhoz (a fő fiókhoz vagy egy alfiókhoz) tartozik, és csak azokat a műveleteket engedi, amelyeket a létrehozáskor kiválasztottál.

Ki hozhat létre API-kulcsot?
A Fejlesztőknek oldalt (Beállítások → Fejlesztőknek) a Tulajdonos és az Adminisztrátor szerepkörű felhasználók érik el, a fő fiókban és az alfiókokban is. A kulcs mindig ahhoz a fiókhoz tartozik, amelyben létrehozod: ha a fiókváltóval egy alfiókba váltasz, az ott létrehozott kulcs az alfiók kulcsa lesz.
Megjegyzés: Kulcsot a REST API modul nélkül is létrehozhatsz, de a hívások csak aktiválás után működnek, addig
402-es választ kapsz. Ezt az oldal is jelzi: „A REST API modul nincs aktiválva. A kulcsok létrehozhatók, de a hívások csak aktiválás után működnek.”
Fő fiók vagy alfiók kulcsa?
| Kulcs | Mit lát és mit tehet |
|---|---|
| Fő fiók kulcsa | A teljes partnerállomány csomagjait látja (a fő fiókét és minden alfiókét). Csomagot a fő fiók nevében ad fel. |
| Alfiók kulcsa | Csak az alfiók saját csomagjait látja. Csomagot az alfiók nevében ad fel, az alfióknak engedélyezett szolgáltatásokkal és telephelyekkel. |
Az alfiók kulcsával feladott csomagra ugyanazok az engedélyek és korlátozások érvényesek, mint a panelen. A csomag díja (price) a szolgáltatói riport feldolgozása után, a jutalékkal együtt jelenik meg.
Tipp: Ha egy alfiók saját webshopot üzemeltet, a webshophoz az alfiókban hozz létre kulcsot. Így a webshop csak a saját csomagjait éri el, és minden csomagja automatikusan az alfiókhoz tartozik.
Jogosultságok
A panelen a jogosultságokat csoportokban látod. Amit a panelen megtehetsz, azt a megfelelő jogosultsággal az API-ból is.
| Jogosultság | Megnevezés a panelen | Végpontok |
|---|---|---|
shipments:read |
Csomagok olvasása | GET /shipments, GET /shipments/{id}, GET /carriers, GET /cod/config, GET /customs/config, GET /locations, GET /locations/{id} |
shipments:write |
Csomagok rögzítése és törlése | POST /shipments, POST /shipments/bulk, POST /shipments/{id}/cancel |
labels:read |
Címkék és vámdokumentumok letöltése | GET /shipments/{id}/label, GET /shipments/{id}/customs/{document}.pdf |
tracking:read |
Nyomkövetés | GET /shipments/{id}/events, GET /tracking/{trackingNumber} |
rates:read |
Előzetes árajánlat (díjtábla szerint) | POST /rates |
charges:read |
Díjtételek olvasása | GET /shipments/{id}/charges |
charges:write |
Díjtételek rögzítése és törlése | POST /shipments/{id}/charges, DELETE /shipments/{id}/charges/{charge} |
pickup_points:read |
Csomagpontok | GET /pickup-points |
cod_check |
Utánvétes vevő ellenőrzése | POST /cod-check |
locations:write |
Telephelyek kezelése | POST /locations, PATCH /locations/{id}, DELETE /locations/{id} |
account:read |
Fiókadatok és csomagkeret | GET /account, GET /account/exports, GET /account/exports/{id} |
account:export |
Teljes adatexport (ZIP) készítése és letöltése | POST /account/exports, GET /account/exports/{id}/download |
customs:read |
Vámtétel-katalógus és EORI-szám olvasása | GET /customs-products, GET /customs-products/{id}, GET /account/eori |
customs:write |
Vámtétel-katalógus és EORI-szám szerkesztése | POST /customs-products, POST /customs-products/import, PUT /customs-products/{id}, DELETE /customs-products/{id}, PUT /account/eori |
manifests:read |
Napzárások olvasása | GET /manifests, GET /manifests/pending, GET /manifests/{id} |
manifests:write |
Napzárás | POST /manifests |
claims:read |
Reklamációk olvasása | GET /claims, GET /claims/{id}, GET /claims/{id}/documents/{document} |
claims:write |
Reklamáció indítása, megjegyzés és dokumentum | POST /claims, POST /claims/{id}/comments, POST /claims/{id}/documents |
claims:manage |
Reklamációk kezelése (benyújtás, eszkalálás) | PATCH /claims/{id}, POST /claims/{id}/submit, POST /claims/{id}/form, POST /claims/{id}/escalate |
carrier_reports:read |
Szolgáltatói riportok olvasása | GET /carrier-reports, GET /carrier-reports/{id}, GET /carrier-reports/{id}/lines, GET /carrier-reports/template.csv |
carrier_reports:write |
Szolgáltatói riportok feltöltése és törlése | POST /carrier-reports, POST /carrier-reports/{id}/reprocess, DELETE /carrier-reports/{id} |
sub_accounts:read |
Alfiókok olvasása | GET /sub-accounts, GET /sub-accounts/{id} |
sub_accounts:write |
Alfiókok kezelése | POST /sub-accounts, PATCH /sub-accounts/{id}, PUT /sub-accounts/{id}/services, PUT /sub-accounts/{id}/locations, PUT /sub-accounts/{id}/shipping-block, POST /sub-accounts/{id}/markups, DELETE /sub-accounts/{id}/markups/{markup} |
webhooks:manage |
Webhookok kezelése | GET /webhooks, POST /webhooks, GET /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/rotate-secret, POST /webhooks/{id}/test, GET /webhooks/events, GET /webhooks/deliveries |
Ha a kulcs olyan végpontot hív, amelyhez nincs jogosultsága, a válasz 403, és a hibaüzenet megnevezi a hiányzó jogosultságot.
Csak a fő fiók kulcsán
Ezeket a panelen is csak a fő fiók kezeli, ezért alfiókban létrehozott kulcshoz nem választhatod ki őket:
charges:read,charges:write(díjtételek: a szolgáltatói díjat és a jutalékot az alfiók nem látja),claims:manage(a reklamációt a fő fiók nyújtja be a szolgáltatónak),carrier_reports:read,carrier_reports:write,sub_accounts:read,sub_accounts:write,locations:write.
Ha ezeket a végpontokat mégis alfiók kulcsával hívod, a válasz 403 („Ez a művelet csak a fő fiók API-kulcsával érhető el.”).
Fontos: A legkisebb szükséges jogosultságot add meg. Egy pénztárba épített csomagpont-kereséshez és vevőellenőrzéshez például elég a Csomagpontok és az Utánvétes vevő ellenőrzése, csomagfeladási jog nem kell hozzá.
Tipikus összeállítások
| Felhasználás | Javasolt jogosultságok |
|---|---|
| Webshop pénztár (csomagpont, vevőellenőrzés) | pickup_points:read, cod_check |
| Webshop-háttérrendszer (feladás, címke, státusz) | shipments:read, shipments:write, labels:read, tracking:read |
| Nemzetközi feladás vámadatokkal | az előző sor, valamint customs:read, customs:write |
| Raktári rendszer (WMS) napzárással | shipments:read, shipments:write, labels:read, manifests:read, manifests:write |
| Ügyfélszolgálati rendszer reklamációkkal | shipments:read, tracking:read, claims:read, claims:write |
| Pénzügyi rendszer (ERP) elszámolással | shipments:read, charges:read, charges:write, carrier_reports:read, carrier_reports:write |
| Partnerkezelő rendszer (alfiókok) | sub_accounts:read, sub_accounts:write, locations:write, account:read |
| Integráció beállítása | webhooks:manage, account:read |
API-kulcs létrehozása
- Nyisd meg a Fejlesztőknek oldalt abban a fiókban, amelyhez a kulcsot létre szeretnéd hozni.
- Kattints az Új kulcs gombra.
- Adj meg egy megnevezést a Megnevezés mezőben, amelyből később is tudni fogod, mire használod (például „UNAS webshop” vagy „Raktári rendszer”).
- Jelöld ki a szükséges jogosultságokat (legalább egyet).
- Kattints a Kulcs létrehozása gombra.
- Másold ki a kulcsot a Másolás gombbal.
Fontos: A teljes kulcs csak egyszer jelenik meg („Új API-kulcs – most másold ki, később nem jelenítjük meg.”). Csak a kulcs kivonatát (hash-ét) tároljuk, így később mi sem tudjuk megmutatni. Ha elveszted, hozz létre újat, a régit pedig vond vissza.
A kulcs vk_live_ előtaggal kezdődik. A listában a kulcs elejét (előtag), a jogosultságait, a létrehozás és az utolsó használat idejét látod („használva …” vagy „még nem volt hívás”).
A kulcs használata
A kulcsot minden hívásban az Authorization fejlécben küldd:
GET /v1/shipments?status=in_transit HTTP/1.1
Host: api.elkuldom.hu
Authorization: Bearer vk_live_…
Accept: application/jsonKulcsonként percenként legfeljebb 120 hívást küldhetsz. A részleteket a REST API – gyors kezdés cikkben találod.
Kulcs visszavonása
- A Fejlesztőknek oldalon keresd meg a kulcsot.
- Kattints a Visszavonás gombra.
A visszavont kulcs azonnal érvénytelen, a vele küldött hívásokra 401-es választ kapsz. A visszavonás végleges.
Kulcscsere leállás nélkül
- Hozz létre új kulcsot ugyanazokkal a jogosultságokkal.
- Állítsd át a rendszeredet az új kulcsra.
- Ellenőrizd az új kulcs utolsó használatának idejét a listában.
- Vond vissza a régi kulcsot.
Biztonsági tanácsok
- A kulcsot csak szerveroldalon használd, ne tedd böngészőben futó kódba vagy mobilalkalmazásba.
- Tárold környezeti változóban vagy titokkezelőben, ne a forráskódban.
- Rendszerenként külön kulcsot használj, hogy ha egy kulcs kiszivárog, a visszavonása ne állítsa le a többi rendszert.
- Ha gyanús használatot látsz, azonnal vond vissza a kulcsot.