Razvijalci

API carinskega preverjanja

Enako preverjanje kot na tem mestu, klicano iz vaše programske opreme. Pošljete spis v JSON in prejmete oceno od 100, blokirne točke, opozorila in priporočene ukrepe — s stabilnimi kodami neskladij in sporočili v 24 uradnih jezikih Evropske unije.

Ustvari ključ Specifikacija OpenAPI

To je API med strežniki. Ključ API je skrivnost. Klici iz brskalnika niso podprti in na overjenih poteh se ne pošiljajo glave CORS: ključ, ki pride v brskalnik, je razkrit ključ.

Pregled

API ponuja kontrolni pogon validatorja: štirinajst presečnih pravil, pet pravil TARIC, štiri pravila o popolnosti dokumentov in validatorje posameznih sistemov deklaracij. Ničesar ne pošilja: preveri obliko in skladnost vaše dokumentacije, obstoj oznak v nomenklaturi in pri uvozu v EU ukrepe TARIC, ki veljajo za poreklo (protidampinške dajatve, nadzor, preference, stopnja dajatve), preden pripravite deklaracijo.

Vse poti nosijo predpono svoje različice. Poti za odkrivanje in specifikacija so javne: integrator ali agent lahko prebere shemo, še preden ima ključ.

Pot	Vloga	Overjanje
POST/v1/checks	Preveri spis in vrne celotno poročilo	Potreben ključ
POST/v1/checks/batch	V enem klicu preveri do 25 spisov	Potreben ključ
GET/v1/me	Vrne trenutni ključ in njegovo kvoto, ne da bi jo porabil	Potreben ključ
GET/v1/declaration-types	Našteje prepoznane vrste deklaracij	Javna
GET/v1/declaration-types/{type}	Opiše polja, pričakovana za posamezno vrsto	Javna
GET/v1/openapi.json	Specifikacija OpenAPI 3.1 tega API	Javna

Overjanje

API se overja z žetonom nosilca. Žeton se prikaže samo enkrat, ob ustvarjanju: shrani se le njegov odtis, zato se izgubljen ključ zamenja, nikoli obnovi.

Hkrati lahko imate tri aktivne ključe, kar omogoča menjavo ključa brez prekinitve integracije: ustvarite novega, ga uvedite in nato prekličite starega.

01Ustvarite ključ v svojem računu, pod »Ključi API«.
02Pošiljajte ga v glavi Authorization vsake zahteve.
03Ob uhajanju ga prekličite: prekinitev je takojšnja, vsebina spisov, oddanih s tem ključem, pa se nemudoma izbriše.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prvo preverjanje

Spis sestavljajo vrsta, glava in blagovne vrstice. Vse vrednosti so nizi: za njihovo tolmačenje poskrbi pogon. Imena polj se odkrijejo med izvajanjem, vrsto za vrsto.

Odgovor pride takoj; potem ni ničesar za poizvedovanje.

Zahteva

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

Branje odgovora

Vsako neskladje nosi tako strojno identiteto kot berljiv stavek. Svojo logiko gradite na strojni identiteti: ta se ne spremeni brez spremembe različice.

severity · code · path · rule: Stabilna pogodbaStabilne. Pojavijo se lahko nove kode; obstoječe se brez spremembe različice ne preimenujejo.
field · message · text: Samo za prikazPrevedeno za prikaz. Ubeseditev se lahko kadar koli spremeni — nikoli jih ne primerjajte v kodi.
engine.version: Spremeni se takoj, ko sprememba pravil premakne oceno nespremenjenega spisa. Arhivirajte jo skupaj s poročili.

Polje »path« zrcali obliko vaše zahteve, zato lahko neskladje povežete neposredno z ustreznim poljem v svojem vmesniku.

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

Odgovor

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

Odkrivanje polj

Vrste deklaracij in njihova polja so javna, ključ ni potreben. To je pot za izdelavo obrazca, za polnjenje preslikave iz vašega ERP ali za to, da agentu daste shemo, ki jo mora izpolniti.

Imena, vrnjena tukaj, so natanko ključi za uporabo v glavi in v vsaki blagovni vrstici. Seznami možnosti se vrnejo razrešeni in prevedeni; dodajte parameter, da jih izpustite, če se vam odgovor zdi pretežak.

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

Paketna obdelava

Do 25 spisov na klic. Odgovor je vedno uspešen, takoj ko je paket sprejet, in vsak vnos nosi svoje stanje: en slabo oblikovan spis nikoli ne podre ostalih.

Če preostala kvota ne pokrije vseh veljavnih vnosov, se zavrne celoten paket, namesto da bi bil obdelan delno — nikoli vam ni treba ugibati, kje se je obdelava ustavila.

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 in orodja

Poleg poti REST sta isti mehanizem in isti podatki dostopna iz pomočnika z umetno inteligenco prek strežnika Model Context Protocol (MCP) ter iz odjemalca API prek že pripravljene zbirke Postman. Oba uporabljata ključ API in dnevno kvoto, opisana zgoraj.

Strežnik MCP

Strežnik MCP omogoča pomočniku, da išče carinske kode, bere uvozno carino EU za kodo, preverja številko EORI, DDV ali AEO v uradnih registrih in preverja osnutek deklaracije, ne da bi napisali eno samo vrstico povezovalne kode. Odgovarja na POST /api/mcp z odgovori JSON.

Je brez stanja in govori obe generaciji protokola: revizijo 2026-07-28, v kateri vsaka zahteva nosi svojo različico, in prejšnje revizije, ki se začnejo s klicem initialize. Povezava, odkrivanje in seznam orodij ne stanejo nič; vsak klic orodja porabi eno enoto dnevne kvote ključa.

Overjanje je isti žeton bearer kot pri API-ju REST. Odjemalec, ki podpira samo prijavo OAuth, na primer spletni konektorji claude.ai, se še ne more povezati: uporabite odjemalca, ki omogoča nastavitev glave.

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	Preveri osnutek deklaracije: ocena od 100, raven in vsaka težava s poljem in ukrepom. Vsebine datoteke ne hrani, razen če se zahteva.
list_declaration_types	Podprti sistemi deklaracij z organom, regijo in pričakovanimi dokumenti.
describe_declaration_type	Polja glave in postavk določene vrste za sestavo vhoda za check_declaration.
search_hs_codes	Kandidatne kode Kombinirane nomenklature glede na opis izdelka v katerem koli od 24 jezikov EU.
describe_hs_code	Ali 4- do 10-mestna koda obstaja v veljavni nomenklaturi, z njeno uradno potjo in besedilom.
lookup_import_duty	Uvozna carina EU za kodo po podatkih TARIC Komisije: carina za tretje države, preferenciali za poreklo, kvote, antidumping in kontrole.
search_chemical	Kemična snov po številki CAS, številki CUS ali imenu v popisu ECICS Komisije: oznaka kombinirane nomenklature, podana za vsak vnos, za preverjanje.
get_quota_balance	Preostalo stanje tarifne kvote EU v zbirki QUOTA Komisije po zaporedni številki ali po oznaki in poreklu: stanje, status (odprta, kritična, blokirana, izčrpana), obdobje in čas branja.
validate_eori	Oblika številke EORI in njen status v uradnem registru (Evropska komisija, HMRC).
validate_vat	Oblika številke DDV EU in njena veljavnost v VIES, z vpisanim imenom, kadar je objavljeno.
check_rex	Oblika številke REX registriranega izvoznika in njeno stanje v zbirki REX Komisije (veljavna, preklicana ali neznana), z datumi.
screen_sanctions	Podjetje, oseba ali plovilo glede na sezname sankcij EU, ZN, Združenega kraljestva in ZDA, ki se posodabljajo vsak dan: vsako ujemanje z oceno, močno ali delno.
search_aeo	Iskanje v zbirki Komisije o pooblaščenih gospodarskih subjektih po imenu podjetja.

Carinske kode so predlogi, povzeti po besedilu nomenklature. Razvrstitev lahko potrdi le deklarant ali zavezujoča tarifna informacija carine.
Carine so okvirne: pogoji, izključitve po državah in izčrpane kvote se ne ocenjujejo. Vsak odgovor nosi referenčni datum izpiska TARIC, ki se osvežuje mesečno.
Register, ki ne odgovori, se sporoči kot nedosegljiv, nikoli kot neveljavna številka. Carini se nikoli ne pošlje nič.

Zbirka Postman

Zbirka se ustvari iz specifikacije OpenAPI, zato ji vedno ustreza: ena zahteva na pot, združene po oznaki, s skeletom telesa za vsak POST. Uvozite jo v Postman, izpolnite spremenljivko apiKey (hranjeno kot skrivnost) in zahteve so pripravljene za pošiljanje.

Prenesi zbirko

Kvota

Vsak ključ ima 500 preverjanj na koledarski dan UTC. Trenutno stanje potuje z vsakim overjenim odgovorom, zato zanj nikoli ne potrebujete dodatnega klica.

Tudi zavrnjeni klici se štejejo: odjemalec, ki se vrti v zanki z neveljavnimi zahtevami, si sam omeji dostop. Kvota je določena na ključ — pišite nam, če potrebujete več.

Odgovor

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

Napake

Sporočila o napakah so samo v angleščini: to so protokolna sporočila, namenjena razvijalcem. Prevedena je le vsebinska plat.

Vsak odgovor nosi identifikator zahteve, ponovljen v telesu. Navedite ga, ko se obrnete na nas — pripelje nas naravnost do klica.

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

Stanje	code	Pomen
400	invalid_json	Telo ni veljaven JSON.
422	invalid_request	JSON je veljaven, njegova vsebina pa ne. Podrobnosti navedejo napačno polje.
401	missing_credentials	Glava Authorization manjka ali je napačno oblikovana.
401	invalid_key	Neznan ključ.
401	key_revoked	Preklican ključ.
403	account_suspended	Račun, ki ima ključ, je začasno onemogočen.
415	unsupported_media_type	Vrsta vsebine ni JSON.
413	payload_too_large	Telo zahteve je preveliko.
429	rate_limit_exceeded	Dnevna kvota je dosežena. Glejte glavo Retry-After.
500	internal_error	Napaka na naši strani. Poskusite znova in nam jo sporočite z identifikatorjem zahteve.

Podatki in hramba

Spisi, poslani prek API, so podatki vaših strank: hranimo čim manj, vi pa imate stikalo, da se ne hrani nič.

Pošljite »store« kot false in nobena vsebina spisa ne bo zapisana: ostaneta le ocena in kode neskladij.
Sicer se vsebina spisov izbriše po 30 dneh.
Preklic ključa takoj izbriše vsebino spisov, ki so bili z njim oddani.
Obdelava poteka v Frankfurtu, zbirka podatkov pa gostuje v Evropski uniji.
Prek API se ne naloži nobena datoteka: le navedete, katere dokumente imate.

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

Kaj ta API ni

Preverjanje pomaga pri pripravi. Ni potrditev carinske uprave, ničesar ne vlaga in ne nadomešča predpisanih obveznosti, ki veljajo za vaš posel.

Carinske oznake se preverjajo glede oblike, obstoja v nomenklaturi in pri uvozu v EU glede ukrepov TARIC za njihovo poreklo, nikoli glede uvrstitve blaga: obstoječa oznaka ostaja oznaka, ki jo je treba preveriti. Ukrepi TARIC so okvirni (mesečni izvleček Evropske komisije): izključitve držav, izčrpane kvote in pogojne dajatve se ne ocenjujejo.