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 mehanizam provjere validatora: trinaest poprečnih pravila, četiri pravila o potpunosti isprava i validatore svojstvene svakom deklaracijskom sustavu. Ništa ne podnosi i ne ispituje nijednu tarifnu bazu — provjerava unutarnju usklađenost i format vašeg predmeta 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.

1Stvorite ključ iz svog računa, u odjeljku „Ključevi API“.
2Šaljite ga u zaglavlju Authorization svakog zahtjeva.
3Opozovite 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": 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 }
}

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

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 šifre provjeravaju se po formatu i usklađenosti s poslom, nikada prema tarifnoj bazi: dobro oblikovana šifra ostaje šifra koju treba provjeriti.