Pro vývojáře

API celní kontroly

Stejná kontrola jako na tomto webu, volaná z vašeho softwaru. Odešlete spis v JSON a získáte skóre ze 100, blokující body, upozornění a doporučené kroky — se stabilními kódy nesrovnalostí a hlášeními ve 24 úředních jazycích Evropské unie.

Vytvořit klíč Specifikace OpenAPI

Toto je API mezi servery. Klíč API je tajemství. Volání z prohlížeče nejsou podporována a na ověřených cestách se neposílají žádné hlavičky CORS: klíč, který se dostane do prohlížeče, je vyzrazený klíč.

Přehled

API zpřístupňuje kontrolní jádro validátoru: čtrnáct průřezových pravidel, pět pravidel TARIC, čtyři pravidla úplnosti dokladů a validátory jednotlivých deklaračních systémů. Nic neodesílá: kontroluje formát a soudržnost vaší dokumentace, existenci kódů v nomenklatuře a u dovozu do EU opatření TARIC platná pro původ (antidumping, kontroly, preference, celní sazba), než připravíte prohlášení.

Každá cesta nese předponu své verze. Cesty pro objevování a specifikace jsou veřejné: integrátor nebo agent si může schéma přečíst ještě dříve, než má klíč.

Cesta	Role	Ověření
POST/v1/checks	Zkontroluje spis a vrátí úplný protokol	Vyžaduje klíč
POST/v1/checks/batch	Zkontroluje až 25 spisů v jednom volání	Vyžaduje klíč
GET/v1/me	Vrátí aktuální klíč a jeho kvótu, aniž by ji čerpal	Vyžaduje klíč
GET/v1/declaration-types	Vypíše rozpoznávané typy prohlášení	Veřejná
GET/v1/declaration-types/{type}	Popíše pole očekávaná pro daný typ	Veřejná
GET/v1/openapi.json	Specifikace OpenAPI 3.1 tohoto API	Veřejná

Ověření

API se ověřuje tokenem bearer. Token se zobrazí jen jednou, při vytvoření: ukládá se pouze jeho otisk, ztracený klíč se tedy nahrazuje, nikdy neobnovuje.

Můžete držet tři aktivní klíče najednou, což umožňuje klíč rotovat bez přerušení integrace: vytvořte nový, nasaďte jej a starý zneplatněte.

01Vytvořte klíč ve svém účtu v sekci „Klíče API“.
02Posílejte jej v hlavičce Authorization každého požadavku.
03Při úniku jej zneplatněte: přerušení je okamžité a obsah spisů odeslaných tímto klíčem se vzápětí smaže.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

První kontrola

Spis se skládá z typu, hlavičky a zbožových položek. Všechny hodnoty jsou řetězce: o jejich výklad se postará engine. Názvy polí se zjišťují za běhu, typ po typu.

Odpověď přijde okamžitě; poté není co dotazovat.

Požadavek

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

Čtení odpovědi

Každá nesrovnalost nese jak strojovou identitu, tak čitelnou větu. Stavte svou logiku na strojové identitě: nemění se bez změny verze.

severity · code · path · rule: Stabilní smlouvaStabilní. Mohou přibýt nové kódy; stávající se bez změny verze nepřejmenovávají.
field · message · text: Pouze zobrazeníPřeloženo pro zobrazení. Formulace se může kdykoli změnit — nikdy je v kódu neporovnávejte.
engine.version: Změní se, jakmile úprava pravidel posune skóre nezměněného spisu. Archivujte ji spolu s protokoly.

Pole „path“ kopíruje tvar vašeho požadavku, takže nesrovnalost můžete napojit přímo na odpovídající pole ve svém rozhraní.

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

Odpověď

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

Objevování polí

Typy prohlášení a jejich pole jsou veřejné, klíč není potřeba. Tuto cestu použijte k sestavení formuláře, k naplnění mapování z vašeho ERP nebo k předání schématu agentovi, který jej má vyplnit.

Zde vrácené názvy jsou přesně ty klíče, které se používají v hlavičce a v každé zbožové položce. Seznamy voleb se vracejí vyřešené a přeložené; přidejte parametr, chcete-li je vynechat, pokud je odpověď pří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é zpracování

Až 25 spisů na volání. Odpověď je vždy úspěšná, jakmile je dávka přijata, a každá položka nese vlastní stav: jeden chybný spis nikdy neshodí ostatní.

Pokud zbývající kvóta nepokryje všechny platné položky, odmítne se celá dávka místo částečného zpracování — nikdy nemusíte hádat, kde se zpracování 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

Kromě tras REST je stejný mechanismus a stejná data dostupná z asistenta s umělou inteligencí prostřednictvím serveru Model Context Protocol (MCP) a z klienta API prostřednictvím hotové kolekce pro Postman. Obojí používá klíč API a denní kvótu popsané výše.

Server MCP

Server MCP umožňuje asistentovi vyhledávat celní kódy, číst dovozní clo pro daný kód, ověřovat číslo EORI, DPH nebo AEO v oficiálních registrech a kontrolovat návrh prohlášení, aniž byste museli napsat jediný řádek spojovacího kódu. Odpovídá na POST /api/mcp, odpovědi jsou ve formátu JSON.

Je bezstavový a mluví oběma generacemi protokolu: revizí 2026-07-28, kde každý požadavek nese svou verzi, a staršími revizemi, které začínají voláním initialize. Připojení, zjišťování a výpis nástrojů nic nestojí; každé volání nástroje spotřebuje jednu jednotku denní kvóty klíče.

Ověřování používá stejný token bearer jako REST API. Klient, který podporuje pouze přihlášení přes OAuth, například webové konektory claude.ai, se zatím nemůže připojit: použijte klienta, který umožňuje nastavit 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 prohlášení: skóre ze 100, úroveň a každý problém s polem a doporučenou akcí. Obsah souboru neukládá, pokud o to nepožádáte.
list_declaration_types	Podporované systémy prohlášení s orgánem, regionem a očekávanými doklady.
describe_declaration_type	Pole záhlaví a položek daného typu, ze kterých se sestaví vstup pro check_declaration.
search_hs_codes	Kandidátní kódy kombinované nomenklatury podle popisu výrobku v kterémkoli ze 24 jazyků EU.
describe_hs_code	Zda 4 až 10místný kód existuje v platné nomenklatuře, s jeho oficiální cestou a zněním.
lookup_import_duty	Dovozní clo EU pro kód podle dat TARIC Komise: clo pro třetí země, preference pro původ, kvóty, antidumping a kontroly.
search_chemical	Chemická látka podle čísla CAS, čísla CUS nebo názvu v soupisu ECICS Komise: kód kombinované nomenklatury uvedený u každé položky, k ověření.
get_quota_balance	Zbývající zůstatek celní kvóty EU v databázi QUOTA Komise podle pořadového čísla nebo podle kódu a původu: zůstatek, stav (otevřená, kritická, blokovaná, vyčerpaná), období a čas načtení.
validate_eori	Formát čísla EORI a jeho stav v oficiálním registru (Evropská komise, HMRC).
validate_vat	Formát čísla DPH EU a jeho platnost ve VIES, včetně zapsaného názvu, pokud je zveřejněn.
check_rex	Formát čísla REX registrovaného vývozce a jeho stav v databázi REX Komise (platné, zrušené nebo neznámé), s daty.
screen_sanctions	Společnost, osoba nebo plavidlo vůči sankčním seznamům EU, OSN, Spojeného království a Spojených států, aktualizovaným každý den: každá shoda se skóre, silná nebo částečná.
search_aeo	Vyhledávání v databázi Komise o schválených hospodářských subjektech podle názvu společnosti.

Celní kódy jsou návrhy převzaté z textu nomenklatury. Zařazení může potvrdit pouze deklarant nebo závazná informace o zařazení zboží od celní správy.
Cla jsou orientační: podmínky, výjimky pro země a vyčerpané kvóty se nevyhodnocují. Každá odpověď nese referenční datum výpisu TARIC, který se obnovuje měsíčně.
Registr, který neodpoví, je hlášen jako nedostupný, nikdy jako neplatné číslo. Celní správě se nikdy nic neposílá.

Kolekce pro Postman

Kolekce se generuje ze specifikace OpenAPI, takže jí vždy odpovídá: jeden požadavek na trasu, seskupené podle značky, s kostrou těla pro každý POST. Importujte ji do Postmanu, vyplňte proměnnou apiKey (uchovávanou jako tajnou) a požadavky jsou připraveny k odeslání.

Stáhnout kolekci

Kvóta

Každý klíč má 500 kontrol na kalendářní den UTC. Aktuální stav cestuje s každou ověřenou odpovědí, takže k jeho zjištění nikdy nepotřebujete další volání.

Počítají se i odmítnutá volání: klient smyčkující na neplatných požadavcích si sám přiškrtí přístup. Kvóta je stanovena na klíč — napište nám, pokud potřebujete více.

Odpověď

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

Chyby

Chybová hlášení jsou pouze anglicky: jde o protokolová hlášení určená vývojářům. Překládá se jen věcný obsah.

Každá odpověď nese identifikátor požadavku, zopakovaný v těle. Uveďte jej, když se na nás obrátíte — dovede nás přímo k danému volání.

{
  "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	Tělo není platný JSON.
422	invalid_request	JSON je platný, ale jeho obsah nikoli. Detail uvádí chybné pole.
401	missing_credentials	Hlavička Authorization chybí nebo je poškozená.
401	invalid_key	Neznámý klíč.
401	key_revoked	Zneplatněný klíč.
403	account_suspended	Účet vlastníka klíče je pozastaven.
415	unsupported_media_type	Typ obsahu není JSON.
413	payload_too_large	Tělo požadavku je příliš velké.
429	rate_limit_exceeded	Denní kvóta vyčerpána. Viz hlavička Retry-After.
500	internal_error	Chyba na naší straně. Zkuste to znovu a nahlaste nám ji s identifikátorem požadavku.

Data a uchovávání

Spisy zaslané přes API jsou data vašich zákazníků: uchováváme co nejméně a vy máte přepínač, jak neuchovat nic.

Pošlete „store“ jako false a žádný obsah spisu se nezapíše: zůstane jen skóre a kódy nesrovnalostí.
Jinak se obsah spisů maže po 30 dnech.
Zneplatnění klíče okamžitě smaže obsah spisů, které jím byly odeslány.
Zpracování probíhá ve Frankfurtu a databáze je hostována v Evropské unii.
Přes API se nenahrávají žádné soubory: pouze uvedete, které doklady máte.

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

Čím toto API není

Kontrola pomáhá s přípravou. Nepředstavuje schválení celní správou, nic nepodává a nenahrazuje regulatorní povinnosti platné pro vaši operaci.

Celní kódy se ověřují na formát, existenci v nomenklatuře a u dovozu do EU na opatření TARIC pro jejich původ, nikdy na zařazení zboží: existující kód zůstává kódem k ověření. Opatření TARIC jsou orientační (měsíční výpis Evropské komise): vyloučení zemí, vyčerpané kvóty a podmíněná cla se nehodnotí.