Fejlesztőknek

Vámellenőrzési API

Ugyanaz az ellenőrzés, mint ezen az oldalon, a saját szoftveréből hívva. Beküld egy aktát JSON-ban, és megkapja a 100-as skálán mért pontszámot, a blokkoló pontokat, a figyelmeztetéseket és az ajánlott lépéseket — állandó hibakódokkal és az Európai Unió 24 hivatalos nyelvére lefordított üzenetekkel.

Kulcs létrehozása OpenAPI-specifikáció

Ez egy szerver–szerver API. Az API-kulcs titok. A böngészőből indított hívások nem támogatottak, és a hitelesített útvonalakon nem küldünk CORS-fejléceket: az a kulcs, amely böngészőbe kerül, kiszivárgott kulcs.

Áttekintés

Az API az ellenőrző motorját teszi elérhetővé: tizennégy átfogó szabály, öt TARIC-szabály, négy dokumentumteljességi szabály és az egyes nyilatkozati rendszerek saját ellenőrzései. Semmit sem továbbít: ellenőrzi a dosszié formátumát és következetességét, a kódok meglétét a nómenklatúrában, valamint uniós behozatalnál a származásra vonatkozó TARIC-intézkedéseket (dömpingellenes vámok, ellenőrzések, kedvezmények, vámtétel), mielőtt elkészítené a nyilatkozatot.

Minden útvonal a verziószámával kezdődik. A felfedező útvonalak és a specifikáció nyilvánosak: egy integrátor vagy egy ágens még kulcs nélkül is elolvashatja a sémát.

Útvonal	Szerep	Hitelesítés
POST/v1/checks	Ellenőriz egy aktát, és visszaadja a teljes jelentést	Kulcs szükséges
POST/v1/checks/batch	Legfeljebb 25 aktát ellenőriz egyetlen hívásban	Kulcs szükséges
GET/v1/me	Visszaadja az aktuális kulcsot és a kvótáját, anélkül hogy fogyasztaná	Kulcs szükséges
GET/v1/declaration-types	Felsorolja a felismert nyilatkozattípusokat	Nyilvános
GET/v1/declaration-types/{type}	Leírja az adott típushoz várt mezőket	Nyilvános
GET/v1/openapi.json	Az API OpenAPI 3.1 specifikációja	Nyilvános

Hitelesítés

Az API bearer tokennel hitelesít. A token csak egyszer, a létrehozáskor jelenik meg: csak a lenyomatát tároljuk, így az elveszett kulcsot lecserélni lehet, visszaszerezni nem.

Egyszerre három aktív kulcsot tarthat, így a kulcsot az integráció megszakítása nélkül cserélheti: hozza létre az újat, vezesse be, majd vonja vissza a régit.

01Hozzon létre kulcsot a fiókjában, az „API-kulcsok” résznél.
02Küldje minden kérés Authorization fejlécében.
03Szivárgás esetén vonja vissza: a megszakítás azonnali, és az ezzel a kulccsal beküldött akták tartalma nyomban törlődik.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Első ellenőrzés

Az akta egy típusból, egy fejlécből és árutételekből áll. Minden érték szöveg: az értelmezésükről a motor gondoskodik. A mezőnevek futásidőben, típusonként deríthetők ki.

A válasz azonnal megérkezik; utána nincs mit lekérdezni.

Kérés

curl https://www.customs-check.com/api/v1/checks \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "import-export",
    "reference": "PO-2026-114",
    "header": {
      "flow": "IM",
      "shipmentCountry": "CN",
      "destinationCountry": "FR",
      "incoterm": "FOB",
      "companyName": "Acme SAS",
      "companyCountry": "FR",
      "eori": "FR12345678900012",
      "transportMode": "sea",
      "currency": "USD",
      "invoiceTotal": "12500"
    },
    "items": [
      {
        "description": "Leather sport shoes",
        "hsCode": "6403990000",
        "quantity": "500",
        "value": "12500",
        "origin": "VN",
        "grossMass": "850",
        "netMass": "800"
      }
    ],
    "documents": { "commercialInvoice": "available", "packingList": "missing" }
  }'

A válasz olvasása

Minden eltérés egyszerre hordoz gépi azonosságot és olvasható mondatot. A logikáját a gépi azonosságra építse: az verzióváltás nélkül nem változik.

severity · code · path · rule: Állandó szerződésÁllandók. Új kódok megjelenhetnek; a meglévőket verzióváltás nélkül nem nevezzük át.
field · message · text: Csak megjelenítésMegjelenítésre fordítva. Bármikor átfogalmazhatók — soha ne hasonlítsa össze őket a kódjában.
engine.version: Akkor változik, ha egy szabálymódosítás elmozdítja egy változatlan akta pontszámát. Archiválja a jelentései mellé.

A „path” mező a kérése szerkezetét tükrözi, így az eltérés közvetlenül az Ön felületén lévő megfelelő mezőhöz köthető.

header.<mező> · items.<n>.<mező> · documents.<category> · global

Válasz

{
  "id": "4c749e25-3408-48f9-b3ca-b18a7ad84681",
  "createdAt": "2026-09-16T12:46:13.186Z",
  "type": "import-export",
  "locale": "en",
  "reference": "PO-2026-114",
  "score": 90,
  "level": "good",
  "counts": { "errors": 0, "warnings": 2, "infos": 1 },
  "documents": { "commercialInvoice": "available", "packingList": "missing" },
  "issues": [
    {
      "severity": "warning",
      "code": "docPackingListMissing",
      "path": "documents.packingList",
      "rule": "DOC-002",
      "params": null,
      "field": "Packing list",
      "message": "Packing list not provided",
      "text": "Packing list not provided"
    },
    {
      "severity": "warning",
      "code": "docTransportMissing",
      "path": "documents.transportDocument",
      "rule": "DOC-003",
      "params": null,
      "field": "Transport document (B/L, AWB, CMR)",
      "message": "Transport document not provided",
      "text": "Transport document not provided"
    }
  ],
  "actions": [
    { "severity": "warning", "code": "docPackingListMissing",
      "path": "documents.packingList", "text": "Add: Packing list" }
  ],
  "tips": [
    {
      "severity": "info",
      "code": "taricControlsPossible",
      "path": "items.0.hsCode",
      "rule": "RULE-017",
      "params": { "measures": "Import control - CITES ; Import control on seal products" },
      "field": "Product 1 — HS / commodity code (if known)",
      "message": "Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply.",
      "text": "Product 1 — HS / commodity code (if known): Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply."
    }
  ],
  "engine": { "version": "1.6.0", "rules": 25, "taric": "2026-10-01" }
}

A mezők felderítése

A nyilatkozattípusok és mezőik nyilvánosak, kulcs nem kell. Ezt az útvonalat használja űrlap építéséhez, ERP-jéből származó megfeleltetés feltöltéséhez, vagy ahhoz, hogy egy ágensnek átadja a kitöltendő sémát.

Az itt visszaadott nevek pontosan azok a kulcsok, amelyeket a fejlécben és minden árutételben használni kell. A választéklisták feloldva és lefordítva érkeznek; adja hozzá a paramétert az elhagyásukhoz, ha a válasz túl terjedelmesnek tűnik.

# The 8 declaration types
curl "https://www.customs-check.com/api/v1/declaration-types?locale=en"

# The fields of one type
curl "https://www.customs-check.com/api/v1/declaration-types/h7?locale=en"

# Same, without the resolved option lists
curl "https://www.customs-check.com/api/v1/declaration-types/h7?options=false"

Kötegelt feldolgozás

Hívásonként legfeljebb 25 akta. A válasz mindig siker, amint a köteget elfogadtuk, és minden tétel a saját állapotát hordozza: egy hibás akta soha nem buktatja el a többit.

Ha a fennmaradó kvóta nem fedezi az összes érvényes tételt, a teljes köteget elutasítjuk ahelyett, hogy részlegesen dolgoznánk fel — soha nem kell találgatnia, hol állt meg a feldolgozás.

curl https://www.customs-check.com/api/v1/checks/batch \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": [ { "type": "h7", "header": {}, "items": [] } ] }'

Ügynökök és eszközök

A REST-útvonalak mellett ugyanaz a motor és ugyanazok az adatok elérhetők egy MI-asszisztensből egy Model Context Protocol (MCP) kiszolgálón át, és egy API-kliensből egy kész Postman-gyűjteményen át. Mindkettő a fent leírt API-kulcsot és napi keretet használja.

MCP-kiszolgáló

Az MCP-kiszolgáló lehetővé teszi, hogy egy asszisztens vámtarifaszámokat keressen, kiolvassa egy kód uniós behozatali vámját, ellenőrizzen egy EORI-, áfa- vagy AEO-számot a hivatalos nyilvántartásokban, és ellenőrizzen egy nyilatkozattervezetet, egyetlen sor kapcsolókód megírása nélkül. A POST /api/mcp címen válaszol, JSON-válaszokkal.

Állapotmentes, és a protokoll mindkét generációját beszéli: a 2026-07-28-i változatot, amelyben minden kérés hordozza a verzióját, és a korábbi változatokat, amelyek initialize hívással kezdődnek. A kapcsolódás, a felfedezés és az eszközök listázása ingyenes; minden eszközhívás a kulcs napi keretének egy egységét használja el.

A hitelesítés ugyanaz a bearer token, mint a REST API-nál. Az a kliens, amely csak OAuth-bejelentkezést támogat, például a claude.ai webes összekötői, még nem tud csatlakozni: használjon olyan klienst, amelyben fejléc állítható.

POST https://www.customs-check.com/api/mcp

claude mcp add --transport http customs-check https://www.customs-check.com/api/mcp \
  --header "Authorization: Bearer $CUSTOM_CHECK_KEY"

check_declaration	Nyilatkozattervezet ellenőrzése: pontszám 100-ból, szint és minden hiba a mezővel és a teendővel. A fájl tartalmát csak kérésre őrzi meg.
list_declaration_types	A támogatott nyilatkozatrendszerek hatósággal, régióval és a várt dokumentumokkal.
describe_declaration_type	Egy típus fejléc- és tételmezői a check_declaration bemenetének összeállításához.
search_hs_codes	Kombinált Nómenklatúra-jelölt kódok egy termékleírás alapján, az EU 24 nyelvének bármelyikén.
describe_hs_code	Létezik-e egy 4–10 számjegyű kód a hatályos nómenklatúrában, hivatalos útvonalával és szövegével.
lookup_import_duty	Egy kód uniós behozatali vámja a Bizottság TARIC-adatai alapján: harmadik országbeli vám, származás szerinti kedvezmények, kontingensek, dömpingellenes intézkedések és ellenőrzések.
search_chemical	Vegyi anyag CAS-szám, CUS-szám vagy név szerint a Bizottság ECICS-jegyzékében: minden tételhez megadott Kombinált Nómenklatúra-kód, ellenőrzésre.
get_quota_balance	Egy uniós vámkontingens fennmaradó egyenlege a Bizottság QUOTA adatbázisában, a sorszám, illetve egy kód és egy származás alapján: egyenleg, állapot (nyitott, kritikus, zárolt, kimerült), időszak és a lekérdezés ideje.
validate_eori	Az EORI-szám formátuma és állapota a hivatalos nyilvántartásban (Európai Bizottság, HMRC).
validate_vat	Az uniós áfaszám formátuma és érvényessége a VIES-ben, a bejegyzett névvel, ha közzétették.
check_rex	Egy regisztrált exportőri (REX) szám formátuma és állapota a Bizottság REX-adatbázisában (érvényes, visszavont vagy ismeretlen), dátumokkal.
screen_sanctions	Egy vállalkozás, személy vagy hajó az EU, az ENSZ, az Egyesült Királyság és az Egyesült Államok naponta frissített szankciós listáin: minden egyezés pontszámmal, erős vagy részleges.
search_aeo	Keresés a Bizottság engedélyezett gazdálkodói adatbázisában cégnév alapján.

A vámtarifaszámok a nómenklatúra szövegéből levezetett javaslatok. A besorolást csak a nyilatkozattevő vagy a vámhatóság kötelező érvényű tarifális felvilágosítása erősítheti meg.
A vámok tájékoztató jellegűek: a feltételeket, az országkizárásokat és a kimerült kontingenseket nem értékeli. Minden válasz tartalmazza a havonta frissített TARIC-kivonat hivatkozási dátumát.
Az a nyilvántartás, amely nem válaszol, elérhetetlenként szerepel, soha nem érvénytelen számként. A vámhatóságnak soha nem küld semmit.

Postman-gyűjtemény

A gyűjtemény az OpenAPI-specifikációból készül, ezért mindig egyezik vele: útvonalanként egy kérés, címke szerint csoportosítva, minden POST-hoz törzsvázzal. Importálja Postmanbe, töltse ki az apiKey változót (titokként tárolva), és a kérések küldésre készek.

A gyűjtemény letöltése

Kvóta

Minden kulcshoz napi 500 ellenőrzés tartozik, UTC naptári nap szerint. Az aktuális állapot minden hitelesített válasszal együtt érkezik, így soha nincs szükség külön hívásra.

Az elutasított hívások is számítanak: az érvénytelen kérésekkel ciklusba került ügyfél önmagát fogja vissza. A kvóta kulcsonként van beállítva — írjon nekünk, ha többre van szüksége.

Válasz

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 437
X-RateLimit-Reset: 1789603200
X-RateLimit-Policy: 500;w=86400

Hibák

A hibaüzenetek csak angolul érhetők el: protokollüzenetek, fejlesztőknek szólnak. Csak a szakmai tartalmat fordítjuk.

Minden válasz kérésazonosítót hordoz, amelyet a törzs is megismétel. Hivatkozzon rá, amikor felveszi velünk a kapcsolatot — egyenesen a hívásig vezet minket.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body failed validation.",
    "details": [
      { "path": "items.0.quantity", "message": "expected a string" }
    ],
    "requestId": "2bbb0946-6178-4b54-921c-b28f794c44bd"
  }
}

Állapot	code	Jelentés
400	invalid_json	A törzs nem érvényes JSON.
422	invalid_request	A JSON érvényes, a tartalma nem. A részletek megnevezik a hibás mezőt.
401	missing_credentials	Hiányzó vagy hibás Authorization fejléc.
401	invalid_key	Ismeretlen kulcs.
401	key_revoked	Visszavont kulcs.
403	account_suspended	A kulcs tulajdonosának fiókja fel van függesztve.
415	unsupported_media_type	A tartalomtípus nem JSON.
413	payload_too_large	A kérés törzse túl nagy.
429	rate_limit_exceeded	A napi kvóta elfogyott. Lásd a Retry-After fejlécet.
500	internal_error	Hiba a mi oldalunkon. Próbálja újra, majd jelezze a kérésazonosítóval.

Adatok és megőrzés

Az API-n beküldött akták az Ön ügyfeleinek adatai: a lehető legkevesebbet tartjuk meg, és Öné a kapcsoló, amellyel semmit sem kell megtartani.

Küldje a „store” mezőt false értékkel, és semmilyen aktatartalom nem íródik ki: csak a pontszám és a hibakódok maradnak meg.
Egyébként az akták tartalmát 30 nap után töröljük.
Egy kulcs visszavonása azonnal törli az azzal beküldött akták tartalmát.
A feldolgozás Frankfurtban történik, az adatbázis az Európai Unióban van.
Az API-n nem tölthető fel fájl: Ön csak azt jelzi, mely okmányokkal rendelkezik.

200 items · 256 KB · 25 / batch · reference ≤ 64

Mi nem ez az API

Az ellenőrzés az előkészítést segíti. Nem minősül a vámhatóság jóváhagyásának, semmit nem nyújt be, és nem váltja ki a műveletére vonatkozó jogszabályi kötelezettségeket.

A vámkódokat formátumra, a nómenklatúrában való meglétükre és uniós behozatalnál a származásukra vonatkozó TARIC-intézkedésekre ellenőrizzük, soha nem az áru besorolására: egy létező kód is ellenőrizendő marad. A TARIC-intézkedések tájékoztató jellegűek (az Európai Bizottság havi kivonata): az országkizárásokat, a kimerült kontingenseket és a feltételes vámokat nem értékeljük.