REST API – műveletek példákkal

Tömeges feladás, vámadat és vámdokumentum, díjtételek, vámtétel-katalógus, napzárás, reklamáció, szolgáltatói riport, alfiókok, telephelyek, fiókadatok és adatexport az API-ból, curl-példákkal.

13 Min. LesezeitAktualisiert: 03.11.2026

Dieser Artikel ist derzeit nur auf Ungarisch verfügbar.

Amit a partnerpanelen megtehetsz, azt a REST API-ból is: ugyanazok a szabályok, jogosultságok és láthatósági szabályok érvényesek, mert a panel és az API ugyanazt a logikát használja. Ez a cikk a csomagfeladáson túli műveleteket mutatja be példákkal. Az alapokat (hitelesítés, lapozás, hibák) a REST API – gyors kezdés cikkben találod.

A példákban az API-kulcs a RACKOON_API_KEY környezeti változóban van:

cURL
export RACKOON_API_KEY="vk_live_…"
API=https://api.elkuldom.hu/v1

Megjegyzés: A fő fiók kulcsa a teljes partnerállományt látja és kezeli. Az alfiók kulcsa csak a saját csomagjait, vámtételeit és reklamációit éri el. A díjtételeket, a szolgáltatói riportokat és az alfiókokat, a telephelyek írását és a reklamációk ügyintézését csak a fő fiók kulcsa éri el (alfiók kulcsával 403).

Fiókadatok és csomagkeret

cURL
curl $API/account -H "Authorization: Bearer $RACKOON_API_KEY"

A válasz a fiók adatai mellett a díjcsomagot (plan), a havi csomagkeretet (quota: limit, used, remaining, percent, korlátlan keretnél limit: null), az aktív modulokat és a kulcs jogosultságait tartalmazza. Jogosultság: account:read.

Tipp: A quota.remaining alapján a saját rendszered előre jelezheti, ha a havi keret fogyóban van. Ha elfogy a keret, a feladásra 422-es hibát kapsz.

Adatexport

Az export a kulcs fiókjának összes adatát tartalmazza egy ZIP-fájlban: táblánként egy CSV-t (UTF-8 BOM-mal, pontosvessző elválasztóval) és a reklamációs dokumentumokat. A fő fiók kulcsával a teljes partnerállomány (alfiókokkal), alfiók kulcsával csak az alfiók saját adatai kerülnek bele. Jelszót, API-kulcsot, webhook-titkot és szolgáltatói hozzáférést nem exportálunk. A fájlok tartalmát az Adatexport és a fiók megszüntetése cikk sorolja fel.

Az export a háttérben készül: az indítás azonnal 202-vel tér vissza, az állapotot (pending, processing, completed, failed) a listában vagy az export azonosítójával kérdezheted le.

cURL
# Indítás (jogosultság: account:export; fiókonként óránként egy, különben 429)
curl -X POST $API/account/exports -H "Authorization: Bearer $RACKOON_API_KEY"

# Állapot (jogosultság: account:read)
curl $API/account/exports/01JA2B3C4D5E6F7G8H9J0K1M2N -H "Authorization: Bearer $RACKOON_API_KEY"

# Letöltés, ha a status completed (jogosultság: account:export)
curl -o export.zip $API/account/exports/01JA2B3C4D5E6F7G8H9J0K1M2N/download -H "Authorization: Bearer $RACKOON_API_KEY"

A válasz counts mezője fájlonként a sorok számát adja. Az elkészült exportot 7 napig töltheted le (expires_at), utána a letöltés 410-es hibát ad. Amíg készül, 409-et.

Megjegyzés: A fiók megszüntetésekor visszavonjuk az API-kulcsokat, ezért az exportidőszakban csak a panelen töltheted le az exportot. Ha az API-n szeretnéd letölteni az adatokat, a megszüntetés előtt indítsd az exportot.

Szabályok az űrlaphoz

Ha saját feladófelületet építesz, ugyanazokat a szabályokat alkalmazhatod, mint a panel:

Végpont Mire jó
GET /carriers Szolgáltatásonként az extra_codes (mely kiegészítők rendelhetők, null = mind) és a cod_countries (mely célországba adható utánvét, null = mindenhová, ahová a szolgáltatás szállít)
GET /cod/config Célországonként az utánvét pénzneme, tizedesjegyei és felső határa (pl. Szlovákia: EUR, két tizedesjegy, Magyarország: HUF, egész szám)
GET /customs/config Mikor kell vámadat (EU-országok, különleges területek), paritások, küldeményjelleg, pénznemek, értékküszöbök, túl általános megnevezések, a fiók EORI-száma

Nemzetközi feladás vámadattal

EU-n kívüli címnél (és az EU vámterületén kívüli különleges területeknél, például a Kanári-szigeteken) a customs objektum kötelező, és a címzett e-mail-címét is meg kell adni.

cURL
curl -X POST $API/shipments \
  -H "Authorization: Bearer $RACKOON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: WS-2001" \
  -d '{
    "carrier": "mpl", "service": "A_121_CSG", "location": "BP-01", "reference": "WS-2001",
    "recipient": { "name": "John Smith", "email": "[email protected]", "phone": "+1 555 0100",
                   "country_code": "US", "postal_code": "10001", "city": "New York", "street": "5th Avenue", "house_number": "1" },
    "parcels": [{ "weight_kg": 1 }],
    "customs": {
      "incoterm": "DAP", "contents_type": "merchandise", "currency": "EUR", "eori": "HU12345678",
      "items": [{ "description": "Pamut férfi póló", "quantity": 2, "value": 40, "weight_kg": 0.4,
                  "hs_code": "61091000", "origin_country": "HU" }]
    }
  }'

A válaszban:

  • customs: a rögzített, ellenőrzött vámadat összesítéssel (total_value, total_weight_kg, eur_value) és a javasolt dokumentumtípussal (document),
  • customs_status: a vámállapot a szolgáltatói események alapján (in_progress, held, released, illetve null),
  • customs_documents: a letölthető vámdokumentumok listája, letöltési címmel.

A vámdokumentum PDF-ben (jogosultság: labels:read):

cURL
curl -o cn22.pdf $API/shipments/01J9Z3K8V4M6Q2R7T5W8X1Y0AB/customs/cn22.pdf \
  -H "Authorization: Bearer $RACKOON_API_KEY"

A választható dokumentumok: commercial_invoice, proforma_invoice, cn22, cn23. Vámadat nélküli csomagnál a válasz 404.

Tipp: Iratkozz fel a shipment.customs_held webhookra: így azonnal értesülsz, ha egy csomag elakad a vámnál. A vámnál várakozó csomagokat a GET /shipments?customs_status=held szűrő listázza.

Tömeges feladás és törlés

Egy hívással legfeljebb 100 csomagot adhatsz fel. Minden tételt külön ellenőrzünk: a hibás tétel nem akasztja meg a többit. Tételenként idempotency_key is megadható.

cURL
curl -X POST $API/shipments/bulk \
  -H "Authorization: Bearer $RACKOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipments": [
      { "idempotency_key": "WS-1042", "carrier": "gls", "service": "HOME", "location": "BP-01", "reference": "WS-1042",
        "recipient": { "name": "Kiss Anna", "phone": "+36301234567", "country_code": "HU", "postal_code": "1052", "city": "Budapest", "street": "Váci utca 12." },
        "parcels": [{ "weight_kg": 1.2 }] },
      { "idempotency_key": "WS-1043", "carrier": "foxpost", "service": "APM", "location": "BP-01", "pickup_point": "…",
        "recipient": { "name": "Nagy Péter", "phone": "+36201234567", "country_code": "HU", "postal_code": "6720", "city": "Szeged", "street": "Kárász utca 9." },
        "parcels": [{ "weight_kg": 0.8, "size_code": "S" }] }
    ]
  }'
JSON
{
    "data": [
        {
            "index": 0,
            "status": "created",
            "shipment": { "id": "…", "status": "created" }
        },
        {
            "index": 1,
            "status": "failed",
            "code": 422,
            "message": "…",
            "errors": {
                "pickup_point": ["Ismeretlen vagy inaktív csomagpont."]
            }
        }
    ],
    "meta": { "succeeded": 1, "failed": 1 }
}

A tétel status mezője: created, replayed (azonos idempotency_key-jel korábban már létrejött), cancelled vagy failed.

Tömeges törlés:

cURL
curl -X POST $API/shipments/bulk \
  -H "Authorization: Bearer $RACKOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "ids": ["01J9Z3…", "01J9Z4…"] }'

Csak piszkozat, rögzített vagy címkenyomtatott csomag törölhető. A többi tétel 409-es, a nem látható tétel 404-es kóddal failed lesz.

Díjtételek (csak fő fiók)

A csomag díja a szolgáltatói riportokból és a kézi tételekből áll össze, erre számoljuk az alfiók jutalékát.

cURL
# Díjösszesítés és tételek
curl $API/shipments/01J9Z3…/charges -H "Authorization: Bearer $RACKOON_API_KEY"

# Kézi felár rögzítése (a díj és a jutalék azonnal újraszámolódik)
curl -X POST $API/shipments/01J9Z3…/charges \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "surcharge", "description": "Túlméret-felár", "amount": 1500 }'

# Kézi tétel törlése
curl -X DELETE $API/shipments/01J9Z3…/charges/88 -H "Authorization: Bearer $RACKOON_API_KEY"

Típusok: shipping, surcharge, cod_fee, insurance, correction, other. Az összeg nettó, negatív is lehet (jóváírás), de nem 0. Riportból származó tételt itt nem törölhetsz (422), ez a riport törlésével vagy újrafeldolgozásával változik. Az alfiók kulcsa a csomagnál csak a jutalékkal növelt price mezőt látja.

Vámtétel-katalógus és EORI-szám

A katalógus fiókonként külön van, és a feladásokból tanul. Az API-ból kereshetsz benne, szerkesztheted, és CSV-ből is feltöltheted.

cURL
# Keresés megnevezésre, SKU-ra vagy HS-kódra
curl "$API/customs-products?q=póló" -H "Authorization: Bearer $RACKOON_API_KEY"

# Mentés (azonos megnevezésnél a meglévő tétel frissül)
curl -X POST $API/customs-products \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "sku": "TS-1", "description": "Pamut férfi póló", "hs_code": "6109 10 00", "origin_country": "HU",
        "unit_value": 20, "currency": "EUR", "unit_weight_kg": 0.2 }'

# CSV-import: sku;megnevezés;hs_kód;származás;egységár;pénznem;egységsúly_kg
curl -X POST $API/customs-products/import \
  -H "Authorization: Bearer $RACKOON_API_KEY" -F "[email protected]"

# EORI-szám mentése
curl -X PUT $API/account/eori \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "eori_number": "HU12345678" }'

Az import válasza: {"data": {"imported": 120, "skipped": 2}}. A hibás sorokat kihagyjuk.

Napzárás

cURL
# Ma zárható csomagok szolgáltatónként és telephelyenként
curl $API/manifests/pending -H "Authorization: Bearer $RACKOON_API_KEY"

# Napzárás futárrendeléssel
curl -X POST $API/manifests \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "carrier": "gls", "location": "BP-01", "request_pickup": true }'

A napzárás a kulcs fiókjának még nem zárt, rögzített vagy címkézett csomagjait zárja le, és manifest.closed webhookot küld. A válasz shipments mezője a lezárt csomagok azonosítóit tartalmazza. Ha nincs zárható csomag, vagy a fiók feladása korlátozott, a válasz 422. Az alfiók kulcsa csak a saját csomagjait zárja le, és csak azokat a napzárásokat látja, amelyekben saját csomagja van.

Reklamációk

Az alfiók kulcsával indított reklamáció alfiók-jelzésként, requested állapotban jön létre. A szolgáltatónak a fő fiók nyújtja be, ahogy a panelen.

cURL
# Reklamáció fényképpel (multipart)
curl -X POST $API/claims \
  -H "Authorization: Bearer $RACKOON_API_KEY" \
  -F "shipment_id=01J9Z3…" -F "type=damage" -F "description=A váza törötten érkezett." \
  -F "claimed_amount=18900" -F "files[0][file][email protected]" -F "files[0][kind]=photo"

# Benyújtás (fő fiók): elkészül a kitöltött nyomtatvány, beáll a válaszhatáridő
curl -X POST $API/claims/12/submit -H "Authorization: Bearer $RACKOON_API_KEY"

# Állapot és összegek (fő fiók)
curl -X PATCH $API/claims/12 \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "paid", "approved_amount": 18900, "paid_amount": 18900 }'

# Megjegyzés, eszkalálás, dokumentum
curl -X POST $API/claims/12/comments -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" -d '{ "body": "Telefonon egyeztetve." }'
curl -X POST $API/claims/12/escalate -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" -d '{ "note": "30 napja nincs válasz." }'
curl -X POST $API/claims/12/documents -H "Authorization: Bearer $RACKOON_API_KEY" -F "files[0][file][email protected]" -F "files[0][kind]=invoice"

A GET /claims/{id} válasza a dokumentumokat letöltési címmel, az eseményeket, a szolgáltató kárügyi szabályait (carrier_rules), fő fiók kulcsánál pedig a szolgáltatónak szóló e-mail-tervezetet (email_draft) is tartalmazza. A belső megjegyzéseket (internal: true, csak fő fiók) az alfiók nem látja. A változásokról claim.created és claim.updated webhook érkezik.

Szolgáltatói riportok (csak fő fiók)

cURL
# Feltöltés és feldolgozás
curl -X POST $API/carrier-reports \
  -H "Authorization: Bearer $RACKOON_API_KEY" \
  -F "[email protected]" -F "carrier=gls" -F "type=invoice" -F "reference=SZLA-2026-1042" -F "period_to=2026-09-30"

# Párosítatlan sorok
curl "$API/carrier-reports/7/lines?filter=unmatched" -H "Authorization: Bearer $RACKOON_API_KEY"

# Újrafeldolgozás (pl. új jutalékszabály után) és törlés
curl -X POST $API/carrier-reports/7/reprocess -H "Authorization: Bearer $RACKOON_API_KEY"
curl -X DELETE $API/carrier-reports/7 -H "Authorization: Bearer $RACKOON_API_KEY"

Típusok: cod_remittance (utánvét-átutalás), invoice (számlamelléklet), delivery (kézbesítési riport). Ugyanazt a fájlt vagy ugyanazt a riportot (szolgáltató, típus és hivatkozás) nem töltheted fel kétszer: a válasz 422, mert a díjak összeadódnának. Mintafájl: GET /carrier-reports/template.csv.

Alfiókok (csak fő fiók)

cURL
# Létrehozás telephellyel
curl -X POST $API/sub-accounts \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Borbolt Hungária", "company_name": "Borbolt Hungária Kft.", "email": "[email protected]", "location_ids": [1] }'

# Engedélyezett szolgáltatások (a teljes lista; az azonosítókat a GET /sub-accounts/{id} adja)
curl -X PUT $API/sub-accounts/5/services \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "service_ids": [3, 4, 9], "extra_service_ids": [12] }'

# 10%-os jutalék minden szolgáltatásra
curl -X POST $API/sub-accounts/5/markups \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "percent", "value": 10 }'

# Feladás korlátozása (pl. lejárt számla miatt)
curl -X PUT $API/sub-accounts/5/shipping-block \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "blocked": true, "message": "Lejárt számla miatt a feladás szünetel." }'

Alfiókot a Business díjcsomagtól hozhatsz létre, más díjcsomagnál a válasz 422 (errors.name). A PATCH /sub-accounts/{id} csak a küldött mezőket módosítja. Az API-ból létrehozott alfiókhoz felhasználót a panel Alfiókok oldalán hívhatsz meg.

Telephelyek

cURL
curl -X POST $API/locations \
  -H "Authorization: Bearer $RACKOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Szegedi raktár", "code": "SZ-01", "country_code": "HU", "postal_code": "6724",
        "city": "Szeged", "street": "Kossuth Lajos sugárút", "house_number": "12", "pickup_days": [1,2,3,4,5] }'

A létrehozáskor megadott sub_account_id az új telephelyet azonnal az alfiókhoz rendeli. A cím- és kapcsolati adatokat létrehozás után nem módosíthatod (422), mert a kiadott címkék és a korábbi csomagok erre a címre hivatkoznak. Új címhez hozz létre új telephelyet. A DELETE /locations/{id} archiválja a telephelyet.

Kapcsolódó cikkek