Żviluppaturi

API tal-verifika doganali

L-istess verifika bħal fuq dan is-sit, imsejħa mis-softwer tiegħek stess. Tibgħat fajl f'JSON u tirċievi punteġġ minn 100, il-punti li jimblukkaw, it-twissijiet u l-azzjonijiet rakkomandati — b'kodiċijiet ta' anomalija stabbli u messaġġi fl-24 lingwa uffiċjali tal-Unjoni Ewropea.

Oħloq ċavetta Speċifikazzjoni OpenAPI

Din hija API minn server għal server. Ċavetta API hija sigriet. Is-sejħiet minn browser mhumiex appoġġati u ma jintbagħat l-ebda header CORS fuq ir-rotot awtentikati: ċavetta li tasal f'browser hija ċavetta mikxufa.

Ħarsa ġenerali

L-API tesponi l-magna tal-kontroll tal-validatur: erbatax-il regola trasversali, ħames regoli TARIC, erba' regoli dwar il-kompletezza tad-dokumenti u l-validaturi ta' kull sistema ta' dikjarazzjoni. Ma tibgħat xejn: tiċċekkja l-format u l-konsistenza tal-fajl tiegħek, l-eżistenza tal-kodiċijiet fin-nomenklatura u, għal importazzjoni fl-UE, il-miżuri TARIC applikabbli għall-oriġini (antidumping, kontrolli, preferenzi, rata tad-dazju), qabel ma tħejji d-dikjarazzjoni.

Kull rotta għandha l-prefiss tal-verżjoni tagħha. Ir-rotot ta' skoperta u l-ispeċifikazzjoni huma pubbliċi: integratur, jew aġent, jista' jaqra l-iskema qabel ma jkollu ċavetta.

Rotta	Rwol	Awtentikazzjoni
POST/v1/checks	Jivverifika fajl u jirritorna r-rapport sħiħ	Tinħtieġ ċavetta
POST/v1/checks/batch	Jivverifika sa 25 fajl f'sejħa waħda	Tinħtieġ ċavetta
GET/v1/me	Jirritorna ċ-ċavetta attwali u l-kwota tagħha, mingħajr ma jikkunsmaha	Tinħtieġ ċavetta
GET/v1/declaration-types	Jelenka t-tipi ta' dikjarazzjoni rikonoxxuti	Pubblika
GET/v1/declaration-types/{type}	Jiddeskrivi l-oqsma mistennija għal tip partikolari	Pubblika
GET/v1/openapi.json	L-ispeċifikazzjoni OpenAPI 3.1 ta' din l-API	Pubblika

Awtentikazzjoni

L-API tawtentika b'token tat-tip bearer. It-token jintwera darba biss, mal-ħolqien: tinżamm biss il-marka tiegħu, għalhekk ċavetta mitlufa tinbidel, qatt ma tiġi rkuprata.

Tista' żżomm tliet ċwievet attivi f'daqqa, li jippermettilek tbiddel ċavetta mingħajr ma tinterrompi l-integrazzjoni tiegħek: oħloq il-ġdida, użaha, u mbagħad irrevoka l-qadima.

01Oħloq ċavetta mill-kont tiegħek, taħt „Ċwievet API“.
02Ibgħatha fil-header Authorization ta' kull talba.
03Irrevokaha jekk tinkixef: il-qtugħ huwa immedjat, u l-kontenut tal-fajls sottomessi b'dik iċ-ċavetta jitħassar minnufih.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

L-ewwel verifika

Fajl huwa magħmul minn tip, intestatura u linji ta' merkanzija. Il-valuri kollha huma stringi: il-magna tieħu ħsieb tinterpretahom. L-ismijiet tal-oqsma jinstabu waqt l-eżekuzzjoni, tip b'tip.

It-tweġiba tasal minnufih; wara m'hemm xejn x'tikkonsulta.

Talba

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

Il-qari tat-tweġiba

Kull anomalija ġġorr kemm identità tal-magna kif ukoll sentenza li tinqara. Ibni l-loġika tiegħek fuq l-identità tal-magna: ma tinbidilx mingħajr bidla fil-verżjoni.

severity · code · path · rule: Kuntratt stabbliStabbli. Jistgħu jitfaċċaw kodiċijiet ġodda; dawk eżistenti ma jissemmewx mill-ġdid mingħajr bidla fil-verżjoni.
field · message · text: Wiri bissTradotti għall-wiri. Jistgħu jiġu riformulati f'kull ħin — qatt m'għandek tqabbilhom fil-kodiċi tiegħek.
engine.version: Tinbidel hekk kif bidla fir-regoli tħarrek il-punteġġ ta' fajl mhux mibdul. Arkivjaha flimkien mar-rapporti tiegħek.

Il-qasam „path“ jirrifletti l-forma tat-talba tiegħek, biex tkun tista' torbot anomalija direttament mal-qasam korrispondenti fl-interfaċċa tiegħek.

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

Tweġiba

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

Skoperta tal-oqsma

It-tipi ta' dikjarazzjoni u l-oqsma tagħhom huma pubbliċi, m'hemmx bżonn ċavetta. Din hija r-rotta biex tibni formola, biex timla mappa mill-ERP tiegħek, jew biex tagħti lil aġent l-iskema li jrid jimla.

L-ismijiet mogħtija hawn huma eżattament iċ-ċwievet li għandhom jintużaw fl-intestatura u f'kull linja ta' merkanzija. Il-listi ta' għażliet jaslu solvuti u tradotti; żid il-parametru biex tħallihom barra jekk it-tweġiba tidhirlek tqila wisq.

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

Ipproċessar f'lott

Sa 25 fajl f'kull sejħa. It-tweġiba hija dejjem suċċess hekk kif jiġi aċċettat il-lott, u kull entrata ġġorr l-istatus tagħha: fajl imfassal ħażin qatt ma jwaqqa' lill-oħrajn.

Jekk il-kwota li fadal ma tkoprix l-entrati validi kollha, jiġi miċħud il-lott kollu minflok ipproċessat parzjalment — qatt ma jkollok taqta' bl-addoċċ fejn waqaf l-ipproċessar.

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

Aġenti u għodod

Minbarra r-rotot REST, l-istess magna u l-istess dejta jistgħu jintlaħqu minn assistent tal-IA, permezz ta' server Model Context Protocol (MCP), u minn klijent API, permezz ta' kollezzjoni Postman lesta. It-tnejn jużaw iċ-ċavetta API u l-kwota ta' kuljum deskritti hawn fuq.

Server MCP

Is-server MCP jippermetti lil assistent ifittex kodiċijiet doganali, jaqra d-dazju fuq l-importazzjoni tal-UE ta' kodiċi, jivverifika numru EORI, tal-VAT jew AEO fir-reġistri uffiċjali, u jikkontrolla abbozz ta' dikjarazzjoni, mingħajr ma tikteb linja waħda ta' kodiċi ta' konnessjoni. Iwieġeb fuq POST /api/mcp, b'risposti JSON.

Huwa mingħajr stat u jitkellem iż-żewġ ġenerazzjonijiet tal-protokoll: ir-reviżjoni 2026-07-28, fejn kull talba ġġorr il-verżjoni tagħha, u r-reviżjonijiet ta' qabel, li jiftħu b'sejħa initialize. Il-konnessjoni, l-iskoperta u l-elenkar tal-għodod ma jiswew xejn; kull sejħa ta' għodda tuża unità waħda tal-kwota ta' kuljum taċ-ċavetta.

L-awtentikazzjoni hija l-istess token bearer tal-API REST. Klijent li jappoġġja biss id-dħul OAuth, bħall-konnetturi web ta' claude.ai, għadu ma jistax jikkonnettja: uża klijent li jħallik issib header.

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	Ikkontrolla abbozz ta' dikjarazzjoni: punteġġ minn 100, livell u kull problema bil-qasam u l-azzjoni. Ma jżommx il-kontenut tal-fajl sakemm ma jintalabx.
list_declaration_types	Is-sistemi ta' dikjarazzjoni appoġġjati, bl-awtorità, ir-reġjun u d-dokumenti mistennija.
describe_declaration_type	L-oqsma tal-header u tal-oġġetti ta' tip, biex jinbena l-input ta' check_declaration.
search_hs_codes	Kodiċijiet kandidati tan-Nomenklatura Magħquda minn deskrizzjoni ta' prodott, f'kwalunkwe waħda mit-24 lingwa tal-UE.
describe_hs_code	Jekk kodiċi ta' 4 sa 10 ċifri jeżistix fin-nomenklatura fis-seħħ, bil-mogħdija u t-test uffiċjali tiegħu.
lookup_import_duty	Dazju fuq l-importazzjoni tal-UE ta' kodiċi mid-dejta TARIC tal-Kummissjoni: dazju ta' pajjiżi terzi, preferenzi għal oriġini, kwoti, kontra d-dumping u kontrolli.
search_chemical	Sustanza kimika permezz ta' numru CAS, numru CUS jew isem fl-inventarju ECICS tal-Kummissjoni: il-kodiċi tan-Nomenklatura Magħquda mogħti għal kull daħla, biex jiġi vverifikat.
get_quota_balance	Bilanċ li fadal ta' kwota tariffarja tal-UE fil-bażi tad-dejta QUOTA tal-Kummissjoni, mill-għadd tal-ordni tagħha jew minn kodiċi u oriġini: bilanċ, stat (miftuħa, kritika, imblukkata, eżawrita), perjodu u ħin tal-qari.
validate_eori	Il-format ta' numru EORI u l-istat tiegħu fir-reġistru uffiċjali (il-Kummissjoni Ewropea, HMRC).
validate_vat	Il-format ta' numru tal-VAT tal-UE u l-validità tiegħu f'VIES, bl-isem irreġistrat meta jkun ippubblikat.
check_rex	Il-format ta' numru REX ta' esportatur irreġistrat u l-istatus tiegħu fil-bażi tad-data REX tal-Kummissjoni (validu, revokat jew mhux magħruf), bid-dati tiegħu.
screen_sanctions	Kumpanija, persuna jew bastiment kontra l-listi tas-sanzjonijiet tal-UE, tan-NU, tar-Renju Unit u tal-Istati Uniti, aġġornati kuljum: kull korrispondenza bil-punteġġ tagħha, qawwija jew parzjali.
search_aeo	Fittex fid-database tal-Kummissjoni tal-Operaturi Ekonomiċi Awtorizzati skont l-isem tal-kumpanija.

Il-kodiċijiet doganali huma suġġerimenti meħuda mill-kliem tan-nomenklatura. Id-dikjarant biss, jew deċiżjoni ta' tagħrif tariffarju vinkolanti mid-dwana, jistgħu jikkonfermaw klassifikazzjoni.
Id-dazji huma indikattivi: il-kundizzjonijiet, l-esklużjonijiet skont il-pajjiż u l-kwoti eżawriti ma jiġux evalwati. Kull tweġiba ġġorr id-data ta' referenza tal-estratt TARIC, aġġornat kull xahar.
Reġistru li ma jwieġebx jiġi rrappurtat bħala mhux disponibbli, qatt bħala numru invalidu. Qatt ma jintbagħat xejn lid-dwana.

Kollezzjoni Postman

Il-kollezzjoni tiġi ġġenerata mill-ispeċifikazzjoni OpenAPI, u għalhekk dejjem taqbel magħha: talba waħda għal kull rotta, miġbura skont it-tikketta, b'skeletru tal-body għal kull POST. Importaha f'Postman, imla l-varjabbli apiKey (miżmum bħala sigriet) u t-talbiet ikunu lesti biex jintbagħtu.

Niżżel il-kollezzjoni

Kwota

Kull ċavetta għandha 500 verifika kuljum skont il-kalendarju UTC. L-istat attwali jivvjaġġa ma' kull tweġiba awtentikata, għalhekk qatt ma jkollok bżonn sejħa addizzjonali biex tkun tafu.

Is-sejħiet miċħuda jgħoddu wkoll: klijent li jibqa' jdur fuq talbiet invalidi jillimita lilu nnifsu. Il-kwota tiġi stabbilita għal kull ċavetta — iktbilna jekk teħtieġ aktar.

Tweġiba

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

Żbalji

Il-messaġġi ta' żball huma bl-Ingliż biss: huma messaġġi ta' protokoll, maħsuba għall-iżviluppaturi. Jiġi tradott biss il-kontenut sostantiv.

Kull tweġiba ġġorr identifikatur tat-talba, ripetut fil-korp. Semmih meta tikkuntattjana — iwassalna dritt għas-sejħa.

{
  "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	Tifsira
400	invalid_json	Il-korp mhuwiex JSON validu.
422	invalid_request	Il-JSON huwa validu iżda l-kontenut tiegħu le. Id-dettalji jsemmu l-qasam żbaljat.
401	missing_credentials	Header Authorization nieqes jew imfassal ħażin.
401	invalid_key	Ċavetta mhux magħrufa.
401	key_revoked	Ċavetta revokata.
403	account_suspended	Il-kont li għandu ċ-ċavetta huwa sospiż.
415	unsupported_media_type	It-tip ta' kontenut mhuwiex JSON.
413	payload_too_large	Il-korp tat-talba huwa kbir wisq.
429	rate_limit_exceeded	Intlaħqet il-kwota ta' kuljum. Ara l-header Retry-After.
500	internal_error	Żball min-naħa tagħna. Erġa' pprova, imbagħad irrappurtahulna bl-identifikatur tat-talba.

Data u żamma

Il-fajls mibgħuta permezz tal-API huma data tal-klijenti tiegħek: inżommu kemm jista' jkun ftit, u għandek swiċċ biex ma nżommu xejn.

Ibgħat „store“ bħala false u ma jinkiteb l-ebda kontenut tal-fajl: jibqgħu biss il-punteġġ u l-kodiċijiet ta' anomalija.
Inkella, il-kontenut tal-fajls jitħassar wara 30 jum.
Ir-revoka ta' ċavetta tħassar minnufih il-kontenut tal-fajls li ntbagħtu biha.
L-ipproċessar isir fi Frankfurt u l-bażi tad-data hija ospitata fl-Unjoni Ewropea.
L-ebda fajl ma jittella' permezz tal-API: int biss tiddikjara liema dokumenti għandek.

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

X'mhijiex din l-API

Il-verifika tgħin fit-tħejjija. Ma tikkostitwixxix validazzjoni mill-amministrazzjoni doganali, ma tissottometti xejn, u ma tissostitwixxix l-obbligi regolatorji applikabbli għall-operazzjoni tiegħek.

Il-kodiċijiet doganali jiġu ċċekkjati għall-format, għall-eżistenza fin-nomenklatura u, għall-importazzjonijiet fl-UE, mal-miżuri TARIC tal-oriġini tagħhom, qatt għall-klassifikazzjoni tal-oġġetti: kodiċi eżistenti jibqa' kodiċi li għandu jiġi vverifikat. Il-miżuri TARIC huma indikattivi (estrazzjoni ta' kull xahar tal-Kummissjoni Ewropea): l-esklużjonijiet ta' pajjiżi, il-kwoti eżawriti u d-dazji kundizzjonali ma jiġux evalwati.