Razvojni programeri

API carinske provjere

Ista provjera kao na ovoj stranici, pozvana iz vašeg softvera. Šaljete predmet u JSON-u i primate ocjenu od 100, blokirajuće točke, upozorenja i preporučene radnje — sa stabilnim šiframa nepravilnosti i porukama na 24 službena jezika Europske unije.

Stvori ključ Specifikacija OpenAPI

Ovo je API između poslužitelja. Ključ API-ja je tajna. Pozivi iz preglednika nisu podržani i na autentificiranim rutama ne šalju se CORS zaglavlja: ključ koji dospije u preglednik je otkriveni ključ.

Pregled

API izlaže kontrolni mehanizam validatora: četrnaest općih pravila, pet pravila TARIC-a, četiri pravila potpunosti dokumentacije i validatore svakog sustava deklaracija. Ništa ne šalje: provjerava format i dosljednost vaše dokumentacije, postojanje oznaka u nomenklaturi te, pri uvozu u EU, mjere TARIC-a koje vrijede za podrijetlo (antidamping, kontrole, povlastice, stopa carine), prije nego što pripremite deklaraciju.

Sve rute nose prefiks svoje verzije. Rute za otkrivanje i specifikacija su javne: integrator ili agent može pročitati shemu i prije nego što ima ključ.

Ruta	Uloga	Autentifikacija
POST/v1/checks	Provjerava predmet i vraća potpuno izvješće	Potreban ključ
POST/v1/checks/batch	Provjerava do 25 predmeta u jednom pozivu	Potreban ključ
GET/v1/me	Vraća trenutni ključ i njegovu kvotu, ne trošeći je	Potreban ključ
GET/v1/declaration-types	Nabraja prepoznate vrste deklaracija	Javna
GET/v1/declaration-types/{type}	Opisuje polja koja se očekuju za pojedinu vrstu	Javna
GET/v1/openapi.json	Specifikacija OpenAPI 3.1 ovog API-ja	Javna

Autentifikacija

API se autentificira nositeljskim tokenom. Token se prikazuje samo jednom, pri stvaranju: čuva se samo njegov otisak, pa se izgubljeni ključ zamjenjuje, nikad ne obnavlja.

Možete istodobno držati tri aktivna ključa, što omogućuje rotaciju ključa bez prekida integracije: stvorite novi, uvedite ga, a zatim opozovite stari.

01Stvorite ključ iz svog računa, u odjeljku „Ključevi API“.
02Šaljite ga u zaglavlju Authorization svakog zahtjeva.
03Opozovite ga u slučaju curenja: prekid je trenutačan, a sadržaj predmeta podnesenih tim ključem odmah se briše.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prva provjera

Predmet se sastoji od vrste, zaglavlja i redaka robe. Sve su vrijednosti nizovi znakova: za njihovo tumačenje brine se mehanizam. Nazivi polja otkrivaju se u izvođenju, vrstu po vrstu.

Odgovor stiže odmah; nakon toga nema se što ispitivati.

Zahtjev

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

Čitanje odgovora

Svaka nepravilnost nosi i strojni identitet i čitljivu rečenicu. Gradite svoju logiku na strojnom identitetu: on se ne mijenja bez promjene verzije.

severity · code · path · rule: Stabilan ugovorStabilne. Mogu se pojaviti nove šifre; postojeće se ne preimenuju bez promjene verzije.
field · message · text: Samo prikazPrevedeno za prikaz. Formulacija se može promijeniti u svakom trenutku — nikada ih ne uspoređujte u kodu.
engine.version: Mijenja se čim promjena pravila pomakne ocjenu nepromijenjenog predmeta. Arhivirajte je zajedno s izvješćima.

Polje „path“ odražava oblik vašeg zahtjeva, pa nepravilnost možete povezati izravno s odgovarajućim poljem u vlastitom sučelju.

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

Otkrivanje polja

Vrste deklaracija i njihova polja su javni, ključ nije potreban. To je ruta za izradu obrasca, za punjenje mapiranja iz vašeg ERP-a ili za predaju sheme agentu koji je mora ispuniti.

Nazivi vraćeni ovdje točno su ključevi koji se koriste u zaglavlju i u svakom retku robe. Popisi opcija vraćaju se razriješeni i prevedeni; dodajte parametar da ih izostavite ako vam se odgovor čini 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"

Skupna obrada

Do 25 predmeta po pozivu. Odgovor je uvijek uspješan čim je skup prihvaćen, a svaki unos nosi vlastiti status: jedan loše oblikovan predmet nikada ne obara ostale.

Ako preostala kvota ne pokriva sve valjane unose, odbija se cijeli skup umjesto djelomične obrade — nikada ne morate nagađati gdje je obrada stala.

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 i alati

Osim REST ruta, isti mehanizam i isti podaci dostupni su iz AI asistenta, putem poslužitelja Model Context Protocol (MCP), i iz API klijenta, putem gotove Postman kolekcije. Oboje koristi API ključ i dnevnu kvotu opisane gore.

MCP poslužitelj

MCP poslužitelj omogućuje asistentu da traži carinske kodove, čita uvozne carine EU-a za kod, provjerava broj EORI, PDV ili AEO u službenim registrima i provjerava nacrt deklaracije, bez ijednog retka vezivnog koda. Odgovara na POST /api/mcp, s JSON odgovorima.

Bez stanja je i govori obje generacije protokola: reviziju 2026-07-28, u kojoj svaki zahtjev nosi svoju verziju, i ranije revizije koje počinju pozivom initialize. Povezivanje, otkrivanje i popis alata ne koštaju ništa; svaki poziv alata troši jednu jedinicu dnevne kvote ključa.

Autentifikacija je isti bearer token kao i za REST API. Klijent koji podržava samo prijavu putem OAuth-a, poput web konektora claude.ai, još se ne može povezati: upotrijebite klijenta koji omogućuje postavljanje zaglavlja.

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	Provjera nacrta deklaracije: ocjena od 100, razina i svaki problem s poljem i radnjom. Ne čuva sadržaj datoteke osim ako se to ne zatraži.
list_declaration_types	Podržani sustavi deklaracija, s tijelom, regijom i očekivanim dokumentima.
describe_declaration_type	Polja zaglavlja i stavki određene vrste, za izradu ulaza za check_declaration.
search_hs_codes	Kandidati iz Kombinirane nomenklature prema opisu proizvoda, na bilo kojem od 24 jezika EU-a.
describe_hs_code	Postoji li kod od 4 do 10 znamenki u važećoj nomenklaturi, s njegovim službenim putem i tekstom.
lookup_import_duty	Uvozna carina EU-a za kod prema podacima TARIC Komisije: carina za treće zemlje, povlastice za podrijetlo, kvote, antidamping i kontrole.
search_chemical	Kemijska tvar prema CAS broju, CUS broju ili nazivu u popisu ECICS Komisije: oznaka kombinirane nomenklature navedena za svaki unos, za provjeru.
get_quota_balance	Preostalo stanje carinske kvote EU-a u bazi QUOTA Komisije, prema rednom broju ili prema oznaci i podrijetlu: stanje, status (otvorena, kritična, blokirana, iscrpljena), razdoblje i vrijeme očitanja.
validate_eori	Format broja EORI i njegov status u službenom registru (Europska komisija, HMRC).
validate_vat	Format broja PDV-a EU-a i njegova valjanost u VIES-u, s upisanim nazivom ako je objavljen.
check_rex	Format REX broja registriranog izvoznika i njegov status u bazi REX Komisije (valjan, opozvan ili nepoznat), s datumima.
screen_sanctions	Poduzeće, osoba ili brod prema popisima sankcija EU-a, UN-a, Ujedinjene Kraljevine i SAD-a, koji se ažuriraju svaki dan: svako podudaranje s ocjenom, snažno ili djelomično.
search_aeo	Pretraga Komisijine baze ovlaštenih gospodarskih subjekata prema nazivu tvrtke.

Carinski kodovi su prijedlozi izvedeni iz teksta nomenklature. Razvrstavanje može potvrditi samo deklarant ili obvezujuća tarifna informacija carine.
Carine su okvirne: uvjeti, isključenja po zemljama i iscrpljene kvote ne ocjenjuju se. Svaki odgovor nosi referentni datum izvatka TARIC-a, koji se osvježava mjesečno.
Registar koji ne odgovara prijavljuje se kao nedostupan, nikada kao nevažeći broj. Carini se nikada ništa ne šalje.

Postman kolekcija

Kolekcija se generira iz specifikacije OpenAPI pa joj uvijek odgovara: jedan zahtjev po ruti, grupiran po oznaci, s kosturom tijela za svaki POST. Uvezite je u Postman, popunite varijablu apiKey (čuva se kao tajna) i zahtjevi su spremni za slanje.

Preuzmi kolekciju

Kvota

Svaki ključ ima 500 provjera po kalendarskom danu UTC. Trenutno stanje putuje uz svaki autentificirani odgovor, pa za njega nikad ne trebate dodatni poziv.

Odbijeni pozivi također se broje: klijent koji se vrti u petlji na neispravnim zahtjevima sam se ograničava. Kvota se određuje po ključu — pišite nam ako vam treba više.

Odgovor

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

Pogreške

Poruke o pogreškama su samo na engleskom: to su protokolne poruke namijenjene razvojnim programerima. Prevodi se samo sadržajni dio.

Svaki odgovor nosi identifikator zahtjeva, ponovljen u tijelu. Navedite ga kada nam se obratite — vodi nas ravno do poziva.

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

Status	code	Značenje
400	invalid_json	Tijelo nije valjan JSON.
422	invalid_request	JSON je valjan, ali njegov sadržaj nije. Pojedinosti navode pogrešno polje.
401	missing_credentials	Zaglavlje Authorization nedostaje ili je loše oblikovano.
401	invalid_key	Nepoznat ključ.
401	key_revoked	Opozvan ključ.
403	account_suspended	Račun vlasnika ključa je suspendiran.
415	unsupported_media_type	Vrsta sadržaja nije JSON.
413	payload_too_large	Tijelo zahtjeva je preveliko.
429	rate_limit_exceeded	Dnevna kvota je dosegnuta. Vidjeti zaglavlje Retry-After.
500	internal_error	Pogreška na našoj strani. Pokušajte ponovno pa nam je prijavite s identifikatorom zahtjeva.

Podaci i čuvanje

Predmeti poslani putem API-ja podaci su vaših klijenata: čuvamo što manje, a vi imate prekidač da se ne čuva ništa.

Pošaljite „store“ kao false i nikakav sadržaj predmeta neće biti zapisan: ostaju samo ocjena i šifre nepravilnosti.
Inače se sadržaj predmeta briše nakon 30 dana.
Opoziv ključa odmah briše sadržaj predmeta koje je podnio.
Obrada se odvija u Frankfurtu, a baza podataka smještena je u Europskoj uniji.
Putem API-ja ne prenosi se nijedna datoteka: samo navodite koje isprave posjedujete.

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

Što ovaj API nije

Provjera pomaže u pripremi. Ne predstavlja potvrdu carinske uprave, ništa ne podnosi i ne zamjenjuje propisane obveze koje se primjenjuju na vaš posao.

Carinske oznake provjeravaju se po formatu, postojanju u nomenklaturi i, pri uvozu u EU, prema mjerama TARIC-a za njihovo podrijetlo, nikada po razvrstavanju robe: postojeća oznaka ostaje oznaka za provjeru. Mjere TARIC-a su okvirne (mjesečni izvadak Europske komisije): isključenja zemalja, iscrpljene kvote i uvjetne carine ne procjenjuju se.