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é: tizenhárom mezőközi szabályt, négy okmány-teljességi szabályt és az egyes nyilatkozati rendszerekhez tartozó validátorokat. Semmit nem továbbít és egyetlen vámtarifa-adatbázist sem kérdez le — az akta belső összhangját és formátumát vizsgálja, mielőtt Ön 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.

1Hozzon létre kulcsot a fiókjában, az „API-kulcsok” résznél.
2Küldje minden kérés Authorization fejlécében.
3Szivá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": 0 },
  "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": [],
  "engine": { "version": "1.0.0", "rules": 13 }
}

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": [] } ] }'

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átum és a művelettel való összhang szempontjából vizsgáljuk, soha nem vetjük össze vámtarifa-adatbázissal: a helyesen felépített kód továbbra is ellenőrzendő kód marad.