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.

8 Min. LesezeitAktualisiert: 03.11.2026

Dieser Artikel ist derzeit nur auf Ungarisch verfügbar.

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.

API-kulcsok és webhookok a Fejlesztőknek oldalon
API-kulcsok és webhookok a Fejlesztőknek oldalon

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

  1. Nyisd meg a Fejlesztőknek oldalt abban a fiókban, amelyhez a kulcsot létre szeretnéd hozni.
  2. Kattints az Új kulcs gombra.
  3. 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”).
  4. Jelöld ki a szükséges jogosultságokat (legalább egyet).
  5. Kattints a Kulcs létrehozása gombra.
  6. 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/json

Kulcsonké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

  1. A Fejlesztőknek oldalon keresd meg a kulcsot.
  2. 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

  1. Hozz létre új kulcsot ugyanazokkal a jogosultságokkal.
  2. Állítsd át a rendszeredet az új kulcsra.
  3. Ellenőrizd az új kulcs utolsó használatának idejét a listában.
  4. 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.

Kapcsolódó cikkek