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ý engine validátora: trinásť prierezových pravidiel, štyri pravidlá úplnosti dokladov a validátory vlastné každému deklaračnému systému. Nič nepodáva ani sa nedopytuje žiadnej colnej sadzobníkovej databázy — overuje vnútornú súdržnosť a formát vášho spisu 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.

1Vytvorte kľúč vo svojom účte v sekcii „Kľúče API“.
2Posielajte ho v hlavičke Authorization každej požiadavky.
3Pri ú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": 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 }
}

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

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 a súlad s operáciou, nikdy proti sadzobníkovej databáze: správne utvorený kód zostáva kódom na overenie.