REST API – gyors kezdés

Alap-URL, Bearer-hitelesítés API-kulccsal, jogosultságok, Idempotency-Key, híváskorlát, hibaformátum, OpenAPI-leírás és a végpontok listája.

12 Min. LesezeitAktualisiert: 03.11.2026

Dieser Artikel ist derzeit nur auf Ungarisch verfügbar.

A Rackoon REST API-jával a saját rendszeredből (webshop, ERP, WMS) adhatsz fel csomagot, tölthetsz le címkét és követheted a státuszokat, minden bekötött szolgáltatónál ugyanazzal az adatmodellel: MPL, GLS, DPD, Express One, FÁMA, Packeta, FoxPost, Fürgefutár, Trans-Pack, UPS és FedEx.

Előfeltételek

  • Aktív REST API modul a Modulok oldalon (14 napos díjmentes próbaidővel). Modul nélkül minden hívásra 402-es választ kapsz.
  • Egy API-kulcs a Fejlesztőknek oldalon. A kulcs létrehozásáról az API-kulcsok és jogosultságok cikk szól.

Alapok

Alap-URL https://api.elkuldom.hu/v1 (a pontos címet a Fejlesztőknek oldal mutatja)
Hitelesítés Authorization: Bearer vk_live_…
Formátum JSON (Content-Type: application/json)
Korlát Kulcsonként 120 hívás percenként, felette 429
Idempotencia Idempotency-Key fejléc csomagfeladáskor, 24 órán át
Leírás OpenAPI 3.1: https://api.elkuldom.hu/v1/openapi.json

A kulcs ahhoz a fiókhoz tartozik, amelyikben létrehoztad. A fő fiók kulcsa a teljes partnerállomány csomagjait látja, az alfiók kulcsa csak az alfiók saját csomagjait.

Első hívás: csomag feladása

cURL
curl -X POST https://api.elkuldom.hu/v1/shipments \
  -H "Authorization: Bearer vk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: WS-1042" \
  -d '{
    "carrier": "gls",
    "service": "PSD_LOCKER",
    "location": "BP-01",
    "reference": "WS-1042",
    "recipient": { "name": "Kiss Anna", "phone": "+36301234567", "email": "[email protected]",
                   "country_code": "HU", "postal_code": "1052",
                   "city": "Budapest", "street": "Váci utca 12." },
    "pickup_point": "…",
    "cod_amount": 12990,
    "parcels": [{ "weight_kg": 1.2 }]
  }'

A kötelező mezők: carrier, service, location, recipient és parcels (1–20 darab). A címzettnél a name, phone, country_code, postal_code, city és street kötelező.

  • carrier: a szolgáltató kódja (mpl, gls, dpd, expressone, fama, packeta, foxpost, furgefutar, transpack, ups, fedex).
  • service: a szolgáltatás kódja. Az elérhető kódokat a GET /carriers adja vissza.
  • location: a feladó telephely kódja vagy azonosítója (GET /locations).
  • pickup_point: a csomagpont azonosítója, csomagpontos és automatás szolgáltatásnál kötelező.
  • type: standard (alapértelmezett), return vagy exchange.
  • draft: true: a csomagot piszkozatként menti.

Sikeres feladáskor a válasz 201 Created, a csomag adatai a data mezőben vannak.

Megjegyzés: Ha az Utánvét Ellenőr modul tiltó módban fut, kockázatos vevőnél az utánvétes csomag feladása 422-es hibával meghiúsul. Lásd: Utánvét Ellenőr.

Idempotencia

Hálózati hiba után a hívást biztonságosan megismételheted, ha Idempotency-Key fejlécet küldesz, például a rendelésszámot:

  • Ha 24 órán belül azonos kulccsal (és azonos API-kulccsal) megismétled a hívást, ugyanazt a csomagot kapod vissza 200-as válasszal és Idempotent-Replayed: true fejléccel. Új csomag nem jön létre.
  • Ha azonos kulccsal még folyamatban van egy hívás, a válasz 409.

Tipp: Minden csomagfeladásnál küldj Idempotency-Key fejlécet. Így egy időtúllépés utáni újrapróbálás sem hoz létre ismétlődő csomagot.

Végpontok

Amit a partnerpanelen megtehetsz, azt az API-ból is: ugyanazok a szabályok, jogosultságok és láthatósági szabályok érvényesek. A műveletek részletes leírását curl-példákkal a REST API – műveletek példákkal cikkben találod. A Fő fiók oszlopban jelölt végpontokat csak a fő fiók kulcsával hívhatod.

Csomagok és nyomkövetés

Metódus és útvonal Leírás Jogosultság Fő fiók
GET /shipments Csomagok listázása (szűrők: status, reference, tracking_number, carrier, updated_since, customs_status, manifest_id; lapozás: page, per_page legfeljebb 100) shipments:read
POST /shipments Csomag feladása (draft: true: piszkozat) shipments:write
POST /shipments/bulk Tömeges feladás (legfeljebb 100) vagy tömeges törlés, tételenkénti eredménnyel shipments:write
GET /shipments/{id} Csomag lekérdezése eseményekkel, vámadattal és vámdokumentumokkal shipments:read
POST /shipments/{id}/cancel Csomag törlése shipments:write
GET /shipments/{id}/label Címke letöltése labels:read
GET /shipments/{id}/customs/{document}.pdf Vámdokumentum (commercial_invoice, proforma_invoice, cn22, cn23) labels:read
GET /shipments/{id}/charges Díjtételek és díjösszesítés (szolgáltatói díj, jutalék) charges:read ✓
POST /shipments/{id}/charges Kézi díjtétel (felár, korrekció) charges:write ✓
DELETE /shipments/{id}/charges/{charge} Kézi díjtétel törlése charges:write ✓
GET /shipments/{id}/events Státusztörténet tracking:read
GET /tracking/{trackingNumber} Keresés nyomkövetési számra tracking:read
POST /rates Előzetes árajánlat csomagpiszkozatra (várható költség szolgáltatásonként, a díjtábla szerint) rates:read

Törzsadatok, fiók és telephelyek

Metódus és útvonal Leírás Jogosultság Fő fiók
GET /carriers Szolgáltatók, szolgáltatások (rendelhető kiegészítők: extra_codes, utánvétes célországok: cod_countries) és kiegészítők shipments:read
GET /cod/config Utánvét pénzneme, tizedesjegyei és felső határa célországonként shipments:read
GET /customs/config Vámszabályok: paritások, küldeményjelleg, pénznemek, küszöbök, különleges területek shipments:read
GET /pickup-points Csomagpontok és automaták keresése pickup_points:read
POST /cod-check Utánvétes vevő ellenőrzése cod_check
GET /account Fiókadatok, díjcsomag, havi csomagkeret, aktív modulok account:read
GET /account/exports, GET /account/exports/{id} Adatexportok és állapotuk account:read
POST /account/exports, GET /account/exports/{id}/download Teljes adatexport (ZIP, CSV-fájlokkal) indítása és letöltése account:export
GET /locations, GET /locations/{id} Feladó telephelyek shipments:read
POST /locations, PATCH /locations/{id}, DELETE /locations/{id} Telephely létrehozása, módosítása, archiválása locations:write ✓

Vám, napzárás, reklamáció

Metódus és útvonal Leírás Jogosultság Fő fiók
GET /customs-products Vámtétel-katalógus (keresés: q) customs:read
POST /customs-products, PUT /customs-products/{id}, DELETE /customs-products/{id} Vámtétel mentése, módosítása, törlése customs:write
POST /customs-products/import CSV-import customs:write
GET /account/eori, PUT /account/eori A fiók EORI-száma customs:read, customs:write
GET /manifests, GET /manifests/{id} Napzárások manifests:read
GET /manifests/pending Ma zárható csomagok szolgáltatónként és telephelyenként manifests:read
POST /manifests Napzárás, opcionális futárrendeléssel manifests:write
GET /claims, GET /claims/{id} Reklamációk claims:read
POST /claims Reklamáció indítása (mellékletekkel is) claims:write
POST /claims/{id}/comments, POST /claims/{id}/documents Megjegyzés, dokumentum feltöltése claims:write
GET /claims/{id}/documents/{document} Dokumentum letöltése claims:read
PATCH /claims/{id} Állapot, összegek, ügyszám, határidő, felelős claims:manage ✓
POST /claims/{id}/submit, POST /claims/{id}/form, POST /claims/{id}/escalate Benyújtás, nyomtatvány, eszkalálás claims:manage ✓

Elszámolás, alfiókok, webhookok

Metódus és útvonal Leírás Jogosultság Fő fiók
GET /carrier-reports, GET /carrier-reports/{id}, GET /carrier-reports/{id}/lines Szolgáltatói riportok és soraik carrier_reports:read ✓
POST /carrier-reports Riport feltöltése (CSV) és feldolgozása carrier_reports:write ✓
POST /carrier-reports/{id}/reprocess, DELETE /carrier-reports/{id} Újrafeldolgozás, törlés carrier_reports:write ✓
GET /sub-accounts, GET /sub-accounts/{id} Alfiókok sub_accounts:read ✓
POST /sub-accounts, PATCH /sub-accounts/{id} Alfiók létrehozása, módosítása sub_accounts:write ✓
PUT /sub-accounts/{id}/services, PUT /sub-accounts/{id}/locations Engedélyezett szolgáltatások, telephelyek sub_accounts:write ✓
PUT /sub-accounts/{id}/shipping-block Feladási korlátozás sub_accounts:write ✓
POST /sub-accounts/{id}/markups, DELETE /sub-accounts/{id}/markups/{markup} Jutalékszabályok sub_accounts:write ✓
GET /webhooks, POST /webhooks, DELETE /webhooks/{id} Webhook-végpontok webhooks:manage
POST /webhooks/{id}/rotate-secret, POST /webhooks/{id}/test Titokcsere, tesztesemény webhooks:manage
GET /webhooks/events, GET /webhooks/deliveries Választható események, kézbesítési napló webhooks:manage

Megjegyzések egyes végpontokhoz

  • Törlés: csak piszkozat, rögzített vagy címkenyomtatott állapotú csomag törölhető, egyébként 409.
  • Címke: ha a címke még nem készült el, a válasz 409.
  • Csomagpontok: a carrier paraméter kötelező. További szűrők: q (név, település, cím vagy pontazonosító), postal_code, type (locker vagy shop), per_page (legfeljebb 200).
  • Utánvét-ellenőrzés: csak az email kötelező. Ha a modul nincs beállítva, 409.
  • Vámdokumentum: csak olyan csomaghoz, amelynek van rögzített vámadata, egyébként 404. A csomaghoz javasolt dokumentumokat a customs_documents lista adja, letöltési címmel.
  • Napzárás: ha nincs zárható csomag, vagy a feladás korlátozott, a válasz 422.

Egységes státuszok

A status mező értékei minden szolgáltatónál azonosak: draft, created, label_printed, handed_over, in_transit, out_for_delivery, at_pickup_point, delivered, failed, returned, cancelled. Az eseményeknél a carrier_status_code a szolgáltató eredeti kódját is tartalmazza.

Díj és utánvét a csomag adataiban

Csomagfeladáskor a saját díjtábládból várható költséget számolunk, ezt a quote mező adja (díjtábla nélkül null). A tényleges díj, a price mező addig null, amíg a fő fiók fel nem tölti és fel nem dolgozza a szolgáltatói riportot. A feldolgozás után:

  • price.total: a csomag nettó díja, alfiók csomagjánál a szolgáltatói díj és a jutalék összege,
  • price.currency: a pénznem.

Az alfiók API-kulcsa így csak a jutalékkal növelt végösszeget látja, a szolgáltatói díjat és a jutalékot külön nem.

Utánvétes csomagnál a cod objektum settled_amount és settled_at mezője a szolgáltatói riport szerint beérkezett utánvét összegét és dátumát mutatja. A riport előtt mindkettő null.

JSON
"cod": { "amount": 12990, "currency": "HUF", "settled_amount": 12990, "settled_at": "2026-10-01T00:00:00+02:00" },
"price": { "total": 1639, "currency": "HUF" }

Részletek: Szolgáltatói riportok: díj és utánvét csomagonként.

Lapozás

A listázó végpontok data és meta mezőt adnak vissza:

JSON
{
  "data": [ … ],
  "meta": { "page": 1, "per_page": 25, "total": 134, "last_page": 6 }
}

Hibakezelés

A hibákat JSON-ban, message mezővel adjuk vissza, validációs hibánál (422) mezőnkénti errors objektummal is:

JSON
{
    "message": "A szolgáltatás nem érhető el ennél a fióknál.",
    "errors": { "service": ["A szolgáltatás nem érhető el ennél a fióknál."] }
}
Kód Jelentés
204 Sikeres törlés, üres válasz
401 Érvénytelen vagy visszavont API-kulcs
402 A REST API modul nincs aktiválva
403 A kulcs nem jogosult a műveletre (a hiányzó jogosultság nevét a message tartalmazza), vagy csak fő fiók kulcsával hívható végpont
403 code: module_inactive: a művelethez szükséges modul nincs bekapcsolva (a module mező nevezi meg, pl. feature.sub_accounts)
404 Nem található
409 Ütközés: nem törölhető csomag, el nem készült címke, folyamatban lévő idempotens hívás, be nem állított Utánvét Ellenőr
422 Validációs hiba vagy üzleti szabály megsértése (pl. elfogyott havi csomagkeret, korlátozott alfiók, ismétlődő riport)
429 Túl sok hívás (120/perc kulcsonként)

Tipp: 429-es válasznál várj, majd ismételd meg a hívást, egyre hosszabb szünetekkel.

Dokumentáció a panelben

A Fejlesztőknek oldalon az API-dokumentáció gomb a teljes, kereshető leírást nyitja meg végpontokkal, paraméterekkel, válaszokkal és sémákkal. Az OpenAPI JSON gombbal letöltheted a géppel olvasható leírást, amelyből klienst is generálhatsz.

Változásnapló

Dátum Verzió Változás
2026-10-18 1.5.0 Új, díjmentes Alfiókok modul (feature.sub_accounts). Kikapcsolt modulnál a /sub-accounts végpontok, az alfiókok API-kulcsai és a POST /locations sub_account_id mezője 403-at adnak code: module_inactive és module mezővel. Az Error séma kiegészült a code és a module mezővel. Azoknál a partnereknél, akiknek már volt alfiókjuk, a modult automatikusan bekapcsoltuk.
2026-10-15 1.4.0 Nem visszafelé kompatibilis: megszűnt a contract mező a csomagon, a napzáráson, a napzárásra váró csoportokon, a GET /carriers elemein, a POST /v1/rates szűrőjében, a tömeges import options.contract beállításában és a napzárás indításakor. Az árajánlatból kikerült a contract_mode, a source értéke own_card vagy live. A GET /account válaszából kikerült a shipping_block_reason. Ha mégis elküldöd a régi mezőt, figyelmen kívül hagyjuk.

Kapcsolódó cikkek