Pre vývojárov

API colnej kontroly

Tá istá kontrola ako na tejto stránke, volaná z vášho softvéru. Odošlete spis v JSON a získate skóre zo 100, blokujúce body, upozornenia a odporúčané kroky — so stabilnými kódmi nezrovnalostí a hláseniami v 24 úradných jazykoch Európskej únie.

Vytvoriť kľúč Špecifikácia OpenAPI

Toto je API medzi servermi. Kľúč API je tajomstvo. Volania z prehliadača nie sú podporované a na overených cestách sa neposielajú žiadne hlavičky CORS: kľúč, ktorý sa dostane do prehliadača, je vyzradený kľúč.

Prehľad

API sprístupňuje kontrolné jadro validátora: štrnásť prierezových pravidiel, päť pravidiel TARIC, štyri pravidlá úplnosti dokladov a validátory jednotlivých deklaračných systémov. Nič neodosiela: kontroluje formát a súdržnosť vašej dokumentácie, existenciu kódov v nomenklatúre a pri dovoze do EÚ opatrenia TARIC platné pre pôvod (antidumping, kontroly, preferencie, colná sadzba), skôr než pripravíte vyhlásenie.

Každá cesta nesie predponu svojej verzie. Cesty na objavovanie a špecifikácia sú verejné: integrátor alebo agent si môže schému prečítať ešte skôr, ako má kľúč.

Cesta	Úloha	Overenie
POST/v1/checks	Skontroluje spis a vráti úplný protokol	Vyžaduje kľúč
POST/v1/checks/batch	Skontroluje až 25 spisov v jednom volaní	Vyžaduje kľúč
GET/v1/me	Vráti aktuálny kľúč a jeho kvótu bez toho, aby ju čerpal	Vyžaduje kľúč
GET/v1/declaration-types	Vypíše rozpoznávané typy vyhlásení	Verejná
GET/v1/declaration-types/{type}	Opíše polia očakávané pre daný typ	Verejná
GET/v1/openapi.json	Špecifikácia OpenAPI 3.1 tohto API	Verejná

Overenie

API sa overuje tokenom bearer. Token sa zobrazí len raz, pri vytvorení: ukladá sa iba jeho odtlačok, stratený kľúč sa teda nahrádza, nikdy neobnovuje.

Môžete držať tri aktívne kľúče naraz, čo umožňuje kľúč rotovať bez prerušenia integrácie: vytvorte nový, nasaďte ho a starý zneplatnite.

01Vytvorte kľúč vo svojom účte v sekcii „Kľúče API“.
02Posielajte ho v hlavičke Authorization každej požiadavky.
03Pri úniku ho zneplatnite: prerušenie je okamžité a obsah spisov odoslaných týmto kľúčom sa vzápätí vymaže.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prvá kontrola

Spis sa skladá z typu, hlavičky a tovarových položiek. Všetky hodnoty sú reťazce: o ich výklad sa postará engine. Názvy polí sa zisťujú za behu, typ po type.

Odpoveď príde okamžite; potom nie je čo dopytovať.

Požiadavka

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" }
  }'

Čítanie odpovede

Každá nezrovnalosť nesie strojovú identitu aj čitateľnú vetu. Stavajte svoju logiku na strojovej identite: nemení sa bez zmeny verzie.

severity · code · path · rule: Stabilná zmluvaStabilné. Môžu pribudnúť nové kódy; existujúce sa bez zmeny verzie nepremenúvajú.
field · message · text: Iba zobrazeniePreložené na zobrazenie. Formulácia sa môže kedykoľvek zmeniť — nikdy ich v kóde neporovnávajte.
engine.version: Zmení sa, len čo úprava pravidiel posunie skóre nezmeneného spisu. Archivujte ju spolu s protokolmi.

Pole „path“ kopíruje tvar vašej požiadavky, takže nezrovnalosť môžete napojiť priamo na zodpovedajúce pole vo svojom rozhraní.

header.<pole> · items.<n>.<pole> · documents.<category> · global

Odpoveď

{
  "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" }
}

Objavovanie polí

Typy vyhlásení a ich polia sú verejné, kľúč nie je potrebný. Túto cestu použite na zostavenie formulára, na naplnenie mapovania z vášho ERP alebo na odovzdanie schémy agentovi, ktorý ju má vyplniť.

Tu vrátené názvy sú presne tie kľúče, ktoré sa používajú v hlavičke a v každej tovarovej položke. Zoznamy možností sa vracajú vyriešené a preložené; pridajte parameter, ak ich chcete vynechať, keď je odpoveď príliš objemná.

# 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"

Dávkové spracovanie

Až 25 spisov na volanie. Odpoveď je vždy úspešná, len čo je dávka prijatá, a každá položka nesie vlastný stav: jeden chybný spis nikdy nezhodí ostatné.

Ak zvyšná kvóta nepokryje všetky platné položky, odmietne sa celá dávka namiesto čiastočného spracovania — nikdy nemusíte hádať, kde sa spracovanie zastavilo.

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

Agenti a nástroje

Okrem trás REST je rovnaký mechanizmus a rovnaké dáta dostupné z asistenta s umelou inteligenciou prostredníctvom servera Model Context Protocol (MCP) a z klienta API prostredníctvom hotovej kolekcie pre Postman. Oboje používa kľúč API a dennú kvótu opísané vyššie.

Server MCP

Server MCP umožňuje asistentovi vyhľadávať colné kódy, čítať dovozné clo EÚ pre daný kód, overovať číslo EORI, DPH alebo AEO v oficiálnych registroch a kontrolovať návrh vyhlásenia, bez toho, aby ste napísali jediný riadok spojovacieho kódu. Odpovedá na POST /api/mcp, odpovede sú vo formáte JSON.

Je bezstavový a hovorí oboma generáciami protokolu: revíziou 2026-07-28, v ktorej každá požiadavka nesie svoju verziu, a staršími revíziami, ktoré začínajú volaním initialize. Pripojenie, zisťovanie a výpis nástrojov nič nestoja; každé volanie nástroja spotrebuje jednu jednotku dennej kvóty kľúča.

Overovanie používa rovnaký token bearer ako REST API. Klient, ktorý podporuje iba prihlásenie cez OAuth, napríklad webové konektory claude.ai, sa zatiaľ nemôže pripojiť: použite klienta, ktorý umožňuje nastaviť hlavičku.

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	Kontrola návrhu vyhlásenia: skóre zo 100, úroveň a každý problém s poľom a odporúčanou akciou. Obsah súboru neukladá, pokiaľ o to nepožiadate.
list_declaration_types	Podporované systémy vyhlásení s orgánom, regiónom a očakávanými dokladmi.
describe_declaration_type	Polia hlavičky a položiek daného typu, z ktorých sa zostaví vstup pre check_declaration.
search_hs_codes	Kandidátske kódy kombinovanej nomenklatúry podľa opisu výrobku v ktoromkoľvek z 24 jazykov EÚ.
describe_hs_code	Či 4- až 10-miestny kód existuje v platnej nomenklatúre, s jeho oficiálnou cestou a znením.
lookup_import_duty	Dovozné clo EÚ pre kód podľa údajov TARIC Komisie: clo pre tretie krajiny, preferencie pre pôvod, kvóty, antidumping a kontroly.
search_chemical	Chemická látka podľa čísla CAS, čísla CUS alebo názvu v zozname ECICS Komisie: kód kombinovanej nomenklatúry uvedený pri každej položke, na overenie.
get_quota_balance	Zostávajúci zostatok colnej kvóty EÚ v databáze QUOTA Komisie podľa poradového čísla alebo podľa kódu a pôvodu: zostatok, stav (otvorená, kritická, blokovaná, vyčerpaná), obdobie a čas načítania.
validate_eori	Formát čísla EORI a jeho stav v oficiálnom registri (Európska komisia, HMRC).
validate_vat	Formát čísla DPH EÚ a jeho platnosť vo VIES, vrátane zapísaného názvu, ak je zverejnený.
check_rex	Formát čísla REX registrovaného vývozcu a jeho stav v databáze REX Komisie (platné, zrušené alebo neznáme), s dátumami.
screen_sanctions	Spoločnosť, osoba alebo plavidlo voči sankčným zoznamom EÚ, OSN, Spojeného kráľovstva a Spojených štátov, aktualizovaným každý deň: každá zhoda so skóre, silná alebo čiastočná.
search_aeo	Vyhľadávanie v databáze Komisie o schválených hospodárskych subjektoch podľa názvu spoločnosti.

Colné kódy sú návrhy prevzaté z textu nomenklatúry. Zatriedenie môže potvrdiť iba deklarant alebo záväzná tarifná informácia colnej správy.
Clá sú orientačné: podmienky, výnimky pre krajiny a vyčerpané kvóty sa nevyhodnocujú. Každá odpoveď nesie referenčný dátum výpisu TARIC, ktorý sa obnovuje mesačne.
Register, ktorý neodpovie, sa hlási ako nedostupný, nikdy ako neplatné číslo. Colnej správe sa nikdy nič neposiela.

Kolekcia pre Postman

Kolekcia sa generuje zo špecifikácie OpenAPI, takže jej vždy zodpovedá: jedna požiadavka na trasu, zoskupené podľa značky, s kostrou tela pre každý POST. Importujte ju do Postmana, vyplňte premennú apiKey (uchovávanú ako tajnú) a požiadavky sú pripravené na odoslanie.

Stiahnuť kolekciu

Kvóta

Každý kľúč má 500 kontrol na kalendárny deň UTC. Aktuálny stav cestuje s každou overenou odpoveďou, takže na jeho zistenie nikdy nepotrebujete ďalšie volanie.

Počítajú sa aj odmietnuté volania: klient v slučke na neplatných požiadavkách si sám priškrtí prístup. Kvóta je stanovená na kľúč — napíšte nám, ak potrebujete viac.

Odpoveď

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

Chyby

Chybové hlásenia sú iba v angličtine: ide o protokolové hlásenia určené vývojárom. Prekladá sa len vecný obsah.

Každá odpoveď nesie identifikátor požiadavky, zopakovaný v tele. Uveďte ho, keď sa na nás obrátite — dovedie nás priamo k danému volaniu.

{
  "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"
  }
}

Stav	code	Význam
400	invalid_json	Telo nie je platný JSON.
422	invalid_request	JSON je platný, ale jeho obsah nie. Detail uvádza chybné pole.
401	missing_credentials	Hlavička Authorization chýba alebo je poškodená.
401	invalid_key	Neznámy kľúč.
401	key_revoked	Zneplatnený kľúč.
403	account_suspended	Účet vlastníka kľúča je pozastavený.
415	unsupported_media_type	Typ obsahu nie je JSON.
413	payload_too_large	Telo požiadavky je príliš veľké.
429	rate_limit_exceeded	Denná kvóta vyčerpaná. Pozrite hlavičku Retry-After.
500	internal_error	Chyba na našej strane. Skúste to znova a nahláste nám ju s identifikátorom požiadavky.

Údaje a uchovávanie

Spisy zaslané cez API sú údaje vašich zákazníkov: uchovávame čo najmenej a vy máte prepínač, ako neuchovať nič.

Pošlite „store“ ako false a žiadny obsah spisu sa nezapíše: zostane len skóre a kódy nezrovnalostí.
Inak sa obsah spisov maže po 30 dňoch.
Zneplatnenie kľúča okamžite vymaže obsah spisov, ktoré ním boli odoslané.
Spracovanie prebieha vo Frankfurte a databáza je hosťovaná v Európskej únii.
Cez API sa nenahrávajú žiadne súbory: iba uvediete, ktoré doklady máte.

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

Čím toto API nie je

Kontrola pomáha s prípravou. Nepredstavuje schválenie colnou správou, nič nepodáva a nenahrádza regulačné povinnosti platné pre vašu operáciu.

Colné kódy sa overujú na formát, existenciu v nomenklatúre a pri dovoze do EÚ na opatrenia TARIC pre ich pôvod, nikdy na zatriedenie tovaru: existujúci kód zostáva kódom na overenie. Opatrenia TARIC sú orientačné (mesačný výpis Európskej komisie): vylúčenia krajín, vyčerpané kvóty a podmienené clá sa nehodnotia.