Ż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-verifika tal-validatur: tlettax-il regola trasversali, erba' regoli dwar il-kompletezza tad-dokumenti u l-validaturi proprji ta' kull sistema ta' dikjarazzjoni. Ma tibgħat xejn u ma tikkonsulta l-ebda bażi tariffarja — tivverifika l-koerenza interna u l-format tal-fajl tiegħek 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.

1Oħloq ċavetta mill-kont tiegħek, taħt „Ċwievet API“.
2Ibgħatha fil-header Authorization ta' kull talba.
3Irrevokaha 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": 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 }
}

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

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 vverifikati fuq il-format u l-koerenza mal-operazzjoni, qatt imqabbla ma' bażi tariffarja: kodiċi mfassal tajjeb jibqa' kodiċi li għandu jiġi vverifikat.