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í engine validátoru: třináct průřezových pravidel, čtyři pravidla úplnosti dokladů a validátory vlastní každému deklaračnímu systému. Nic nepodává ani se nedotazuje žádné celní sazebníkové databáze — ověřuje vnitřní soudržnost a formát vašeho spisu dříve, 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.

1Vytvořte klíč ve svém účtu v sekci „Klíče API“.
2Posílejte jej v hlavičce Authorization každého požadavku.
3Př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": 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 }
}

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

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 a soulad s operací, nikdy proti sazebníkové databázi: správně utvořený kód zůstává kódem k ověření.