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.
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 -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 aGET /carriersadja 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),returnvagyexchange.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 ésIdempotent-Replayed: truefejlé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-Keyfejlé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
carrierparaméter kötelező. További szűrők:q(név, település, cím vagy pontazonosító),postal_code,type(lockervagyshop),per_page(legfeljebb 200). - Utánvét-ellenőrzés: csak az
emailkö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 acustoms_documentslista 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.
"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:
{
"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:
{
"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. |