Arendajatele

Tollikontrolli API

Sama kontroll nagu sellel saidil, välja kutsutud teie enda tarkvarast. Saadate toimiku JSON-vormingus ja saate skoori sajast, takistavad punktid, hoiatused ja soovitatud sammud — püsivate kõrvalekallete koodidega ja teadetega Euroopa Liidu 24 ametlikus keeles.

Loo võti OpenAPI spetsifikatsioon

See on serverilt serverile API. API võti on saladus. Brauserist tehtud päringuid ei toetata ja autenditud teedel CORS-päiseid ei saadeta: brauserisse jõudnud võti on lekkinud võti.

Ülevaade

API avab kontrollija kontrollimootori: neliteist üldreeglit, viis TARICu reeglit, neli dokumentide täielikkuse reeglit ja iga deklaratsioonisüsteemi omad kontrollid. See ei saada midagi: kontrollib teie toimiku vormingut ja kooskõla, koodide olemasolu nomenklatuuris ning ELi importimisel päritolule kehtivaid TARICu meetmeid (dumpinguvastased tollimaksud, kontrollid, soodustused, tollimaksumäär), enne kui deklaratsiooni koostate.

Kõigil teedel on eesliiteks nende versioon. Avastusteed ja spetsifikatsioon on avalikud: integreerija või agent saab skeemi lugeda enne võtme omamist.

Tee	Roll	Autentimine
POST/v1/checks	Kontrollib toimikut ja tagastab täieliku aruande	Võti nõutav
POST/v1/checks/batch	Kontrollib ühe päringuga kuni 25 toimikut	Võti nõutav
GET/v1/me	Tagastab praeguse võtme ja selle kvoodi, seda kulutamata	Võti nõutav
GET/v1/declaration-types	Loetleb tuntud deklaratsiooniliigid	Avalik
GET/v1/declaration-types/{type}	Kirjeldab ühe liigi puhul oodatavaid välju	Avalik
GET/v1/openapi.json	Selle API OpenAPI 3.1 spetsifikatsioon	Avalik

Autentimine

API autendib kandjatunnusega. Tunnust näidatakse vaid korra, loomise hetkel: säilitatakse ainult selle jäljend, seega kaotatud võti asendatakse, mitte kunagi ei taastata.

Korraga võite hoida kolme aktiivset võtit, mis võimaldab võtit vahetada ilma lõimingut katkestamata: looge uus, võtke kasutusele ja seejärel tühistage vana.

01Looge võti oma kontol jaotises „API võtmed“.
02Saatke see iga päringu Authorization-päises.
03Lekke korral tühistage see: katkestus on kohene ja selle võtmega esitatud toimikute sisu kustutatakse otsekohe.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Esimene kontroll

Toimik koosneb liigist, päisest ja kaubaridadest. Kõik väärtused on sõned: nende tõlgendamise eest hoolitseb mootor. Väljade nimed selguvad käitusajal, liik liigi haaval.

Vastus saabub kohe; pärast seda pole midagi pärida.

Päring

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

Vastuse lugemine

Iga kõrvalekalle kannab korraga masinidentiteeti ja loetavat lauset. Ehitage oma loogika masinidentiteedile: see ei muutu ilma versioonivahetuseta.

severity · code · path · rule: Püsiv lepingPüsivad. Uusi koode võib lisanduda; olemasolevaid ei nimetata ümber ilma versioonivahetuseta.
field · message · text: Ainult kuvamiseksTõlgitud kuvamiseks. Neid võidakse igal ajal ümber sõnastada — ärge kunagi võrrelge neid oma koodis.
engine.version: Muutub niipea, kui reeglimuudatus nihutab muutumatu toimiku skoori. Arhiveerige see koos oma aruannetega.

Väli „path“ peegeldab teie päringu kuju, nii et saate kõrvalekalde siduda otse vastava väljaga oma liideses.

header.<väli> · items.<n>.<väli> · documents.<category> · global

Vastus

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

Väljade avastamine

Deklaratsiooniliigid ja nende väljad on avalikud, võtit pole vaja. See on tee vormi koostamiseks, ERP-st pärineva vastenduse toitmiseks või skeemi andmiseks agendile, kes peab selle täitma.

Siin tagastatud nimed on täpselt need võtmed, mida kasutada päises ja igal kaubareal. Valikuloendid tulevad lahendatult ja tõlgitult; lisage parameeter nende ärajätmiseks, kui vastus tundub liiga mahukas.

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

Pakktöötlus

Kuni 25 toimikut päringu kohta. Vastus on alati edukas, kui pakk on vastu võetud, ja iga kirje kannab oma olekut: üks vigane toimik ei kukuta kunagi teisi läbi.

Kui järelejäänud kvoot ei kata kõiki kehtivaid kirjeid, lükatakse tagasi kogu pakk, mitte ei töödelda seda osaliselt — te ei pea kunagi arvama, kus töötlus peatus.

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

Agendid ja tööriistad

Lisaks REST-marsruutidele on sama mootor ja samad andmed kättesaadavad tehisintellekti assistendile Model Context Protocol (MCP) serveri kaudu ning API kliendile valmis Postmani kogumi kaudu. Mõlemad kasutavad eespool kirjeldatud API võtit ja päevakvooti.

MCP server

MCP server võimaldab assistendil otsida tollikoode, lugeda koodi ELi impordimaksu, kontrollida EORI-, käibemaksu- või AEO-numbrit ametlikest registritest ja kontrollida deklaratsiooni mustandit, ilma et peaksite kirjutama ainsatki rida sidumiskoodi. Ta vastab aadressil POST /api/mcp, JSON-vastustega.

See on olekuta ja räägib protokolli mõlemat põlvkonda: redaktsiooni 2026-07-28, kus iga päring kannab oma versiooni, ning varasemaid redaktsioone, mis algavad initialize-kutsega. Ühendus, avastamine ja tööriistade loetlemine on tasuta; iga tööriista kutse kulutab ühe ühiku võtme päevakvoodist.

Autentimine on sama bearer-token nagu REST API-l. Klient, mis toetab ainult OAuth-sisselogimist, näiteks claude.ai veebiühendused, ei saa veel ühendust luua: kasutage klienti, mis võimaldab päist määrata.

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	Deklaratsiooni mustandi kontroll: hinne 100-st, tase ja iga probleem koos välja ja tegevusega. Faili sisu ei säilitata, kui seda ei palutud.
list_declaration_types	Toetatud deklareerimissüsteemid koos asutuse, piirkonna ja oodatavate dokumentidega.
describe_declaration_type	Tüübi päise- ja kaubaväljad, et koostada check_declaration sisend.
search_hs_codes	Kombineeritud nomenklatuuri kandidaatkoodid toote kirjelduse järgi mis tahes ELi 24 keelest.
describe_hs_code	Kas 4–10-kohaline kood on kehtivas nomenklatuuris olemas, koos ametliku tee ja sõnastusega.
lookup_import_duty	Koodi ELi impordimaks komisjoni TARIC-andmete põhjal: kolmandate riikide tollimaks, päritolusoodustused, kvoodid, dumpinguvastased meetmed ja kontrollid.
search_chemical	Keemiline aine CAS-numbri, CUS-numbri või nime järgi komisjoni ECICS-i registris: iga kirje kohta antud kombineeritud nomenklatuuri kood, kontrollimiseks.
get_quota_balance	ELi tariifikvoodi allesjäänud jääk komisjoni QUOTA andmebaasis järjekorranumbri või koodi ja päritolu järgi: jääk, olek (avatud, kriitiline, blokeeritud, ammendatud), periood ja lugemise aeg.
validate_eori	EORI-numbri vorming ja selle olek ametlikus registris (Euroopa Komisjon, HMRC).
validate_vat	ELi käibemaksunumbri vorming ja selle kehtivus VIESis, koos registreeritud nimega, kui see on avaldatud.
check_rex	Registreeritud eksportija REX-numbri vorming ja selle olek komisjoni REX-andmebaasis (kehtiv, tühistatud või tundmatu) koos kuupäevadega.
screen_sanctions	Ettevõte, isik või laev ELi, ÜRO, Ühendkuningriigi ja Ameerika Ühendriikide iga päev uuendatavate sanktsioonide nimekirjade alusel: iga vaste koos skooriga, tugev või osaline.
search_aeo	Komisjoni volitatud ettevõtjate andmebaasi otsing ettevõtte nime järgi.

Tollikoodid on nomenklatuuri sõnastusest tuletatud ettepanekud. Klassifikatsiooni saab kinnitada ainult deklarant või tolli siduv tariifiteave.
Tollimaksud on orienteeruvad: tingimusi, riigipõhiseid erandeid ja ammendunud kvoote ei hinnata. Iga vastus kannab TARIC-väljavõtte võrdluskuupäeva, mida uuendatakse igakuiselt.
Register, mis ei vasta, märgitakse kättesaamatuks, mitte kunagi kehtetuks numbriks. Tollile ei saadeta kunagi midagi.

Postmani kogum

Kogum luuakse OpenAPI spetsifikatsioonist, seega on see sellega alati kooskõlas: üks päring marsruudi kohta, rühmitatud sildi järgi, iga POST-i jaoks keha karkass. Importige see Postmani, täitke muutuja apiKey (hoitakse saladusena) ja päringud on saatmiseks valmis.

Laadi kogum alla

Kvoot

Igal võtmel on 500 kontrolli UTC kalendripäeva kohta. Praegune seis rändab kaasa iga autenditud vastusega, seega ei vaja te selle teadasaamiseks kunagi lisapäringut.

Ka tagasi lükatud päringud lähevad arvesse: klient, kes tsükleldab kehtetute päringutega, piirab iseennast. Kvoot on seatud võtme kohta — kirjutage meile, kui vajate rohkem.

Vastus

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

Vead

Veateated on ainult inglise keeles: need on protokolliteated, mõeldud arendajatele. Tõlgitakse ainult sisuline osa.

Iga vastus kannab päringu tunnust, mida korratakse kehas. Viidake sellele meiega ühendust võttes — see viib meid otse selle päringuni.

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

Olek	code	Tähendus
400	invalid_json	Keha ei ole kehtiv JSON.
422	invalid_request	JSON on kehtiv, kuid selle sisu mitte. Üksikasjad nimetavad vigase välja.
401	missing_credentials	Authorization-päis puudub või on vigane.
401	invalid_key	Tundmatu võti.
401	key_revoked	Tühistatud võti.
403	account_suspended	Võtme omanikukonto on peatatud.
415	unsupported_media_type	Sisutüüp ei ole JSON.
413	payload_too_large	Päringu keha on liiga suur.
429	rate_limit_exceeded	Päevane kvoot on täis. Vaadake Retry-After päist.
500	internal_error	Viga meie poolel. Proovige uuesti ja teatage meile päringu tunnusega.

Andmed ja säilitamine

API kaudu saadetud toimikud on teie klientide andmed: säilitame võimalikult vähe ja teil on lüliti, et mitte midagi ei säilitataks.

Saatke „store“ väärtusega false ja toimiku sisu ei kirjutata üldse: alles jäävad vaid skoor ja kõrvalekallete koodid.
Vastasel juhul kustutatakse toimikute sisu 30 päeva pärast.
Võtme tühistamine kustutab kohe sellega esitatud toimikute sisu.
Töötlus toimub Frankfurdis ja andmebaas asub Euroopa Liidus.
API kaudu faile üles ei laadita: te üksnes märgite, millised dokumendid teil on.

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

Mis see API ei ole

Kontroll aitab ettevalmistusel. See ei ole tolliameti kinnitus, see ei esita midagi ega asenda teie tehingule kohalduvaid õigusnõudeid.

Tollikoode kontrollitakse vormingu, nomenklatuuris olemasolu ja ELi importimisel nende päritolu TARICu meetmete suhtes, kuid mitte kunagi kauba klassifikatsiooni suhtes: olemasolev kood jääb kontrollitavaks koodiks. TARICu meetmed on soovituslikud (Euroopa Komisjoni igakuine väljavõte): riikide välistusi, ammendatud kvoote ja tingimuslikke tollimakse ei hinnata.