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.
This article is currently available in Hungarian only.
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:
export RACKOON_API_KEY="vk_live_…"
API=https://api.elkuldom.hu/v1Megjegyzé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 $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.remainingalapján a saját rendszered előre jelezheti, ha a havi keret fogyóban van. Ha elfogy a keret, a feladásra422-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.
# 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 -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, illetvenull),customs_documents: a letölthető vámdokumentumok listája, letöltési címmel.
A vámdokumentum PDF-ben (jogosultság: labels:read):
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_heldwebhookra: így azonnal értesülsz, ha egy csomag elakad a vámnál. A vámnál várakozó csomagokat aGET /shipments?customs_status=heldszű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 -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" }] }
]
}'{
"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 -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.
# 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.
# 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
# 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.
# 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)
# 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)
# 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 -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.