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 izpostavlja preverjevalni pogon validatorja: trinajst prečnih pravil, štiri pravila o popolnosti dokumentov in validatorje, lastne vsakemu deklaracijskemu sistemu. Ničesar ne pošilja in ne poizveduje po nobeni tarifni zbirki — preverja notranjo skladnost in obliko vašega spisa, 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.

1Ustvarite ključ v svojem računu, pod »Ključi API«.
2Pošiljajte ga v glavi Authorization vsake zahteve.
3Ob 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": 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 }
}

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

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 kode se preverjajo glede oblike in skladnosti s poslom, nikoli proti tarifni zbirki: dobro oblikovana koda ostaja koda, ki jo je treba preveriti.