Kūrėjams

Muitinės patikros API

Ta pati patikra kaip šioje svetainėje, iškviečiama iš jūsų programinės įrangos. Atsiunčiate bylą JSON formatu ir gaunate balą iš 100, blokuojančius punktus, įspėjimus ir rekomenduojamus veiksmus — su stabiliais neatitikimų kodais ir pranešimais 24 oficialiosiomis Europos Sąjungos kalbomis.

Sukurti raktą OpenAPI specifikacija

Tai serverio–serverio API. API raktas yra paslaptis. Iškvietimai iš naršyklės nepalaikomi, o autentifikuotuose keliuose CORS antraštės nesiunčiamos: raktas, patekęs į naršyklę, yra nutekėjęs raktas.

Apžvalga

API atveria tikrintuvo patikros variklį: trylika skersinių taisyklių, keturias dokumentų išsamumo taisykles ir kiekvienai deklaravimo sistemai būdingus tikrintuvus. Jis nieko neperduoda ir nesikreipia į jokią tarifų duomenų bazę — jis tikrina jūsų bylos vidinį nuoseklumą ir formatą prieš jums rengiant deklaraciją.

Visi keliai turi savo versijos priešdėlį. Atradimo keliai ir specifikacija yra vieši: integruotojas arba agentas gali perskaityti schemą dar neturėdamas rakto.

Kelias	Vaidmuo	Autentifikavimas
POST/v1/checks	Patikrina bylą ir grąžina visą ataskaitą	Reikia rakto
POST/v1/checks/batch	Vienu iškvietimu patikrina iki 25 bylų	Reikia rakto
GET/v1/me	Grąžina esamą raktą ir jo kvotą jos nenaudodamas	Reikia rakto
GET/v1/declaration-types	Išvardija atpažįstamus deklaracijų tipus	Viešas
GET/v1/declaration-types/{type}	Aprašo laukus, kurių tikimasi konkrečiam tipui	Viešas
GET/v1/openapi.json	Šio API OpenAPI 3.1 specifikacija	Viešas

Autentifikavimas

API autentifikuojasi nešiklio prieigos raktu. Raktas parodomas tik kartą, kuriant: saugoma tik jo santrauka, todėl pamestas raktas pakeičiamas, bet niekada neatkuriamas.

Vienu metu galite turėti tris aktyvius raktus, todėl raktą galite pakeisti nenutraukdami integracijos: sukurkite naują, įdiekite jį, tada panaikinkite senąjį.

1Sukurkite raktą savo paskyroje, skiltyje „API raktai“.
2Siųskite jį kiekvienos užklausos Authorization antraštėje.
3Nutekėjus panaikinkite jį: nutraukimas yra nedelsiamas, o tuo raktu pateiktų bylų turinys tuoj pat ištrinamas.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pirmoji patikra

Bylą sudaro tipas, antraštė ir prekių eilutės. Visos reikšmės yra eilutės: jų interpretavimu pasirūpina variklis. Laukų pavadinimai atrandami vykdymo metu, tipas po tipo.

Atsakas ateina iš karto; vėliau nieko nereikia užklausti.

Užklausa

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

Atsako skaitymas

Kiekvienas neatitikimas turi ir mašininę tapatybę, ir skaitomą sakinį. Kurkite savo logiką ant mašininės tapatybės: ji nesikeičia be versijos pakeitimo.

severity · code · path · rule: Stabili sutartisStabilūs. Gali atsirasti naujų kodų; esami nepervadinami be versijos pakeitimo.
field · message · text: Tik rodymuiIšversta rodymui. Formuluotė gali bet kada pasikeisti — niekada jų nelyginkite savo kode.
engine.version: Pasikeičia, kai taisyklių pakeitimas pakeičia nepakitusios bylos balą. Archyvuokite ją kartu su ataskaitomis.

Laukas „path“ atkartoja jūsų užklausos formą, todėl neatitikimą galite susieti tiesiai su atitinkamu lauku savo sąsajoje.

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

Atsakas

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

Laukų atradimas

Deklaracijų tipai ir jų laukai yra vieši, rakto nereikia. Tai kelias formai sukurti, susiejimui iš jūsų ERP maitinti arba agentui pateikti schemą, kurią jis turi užpildyti.

Čia grąžinami pavadinimai yra būtent tie raktai, kuriuos reikia naudoti antraštėje ir kiekvienoje prekių eilutėje. Pasirinkimų sąrašai grąžinami išspręsti ir išversti; pridėkite parametrą, kad juos praleistumėte, jei atsakas atrodo per sunkus.

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

Paketinis apdorojimas

Iki 25 bylų vienam iškvietimui. Atsakas visada sėkmingas, kai paketas priimamas, ir kiekvienas įrašas turi savo būseną: viena netaisyklinga byla niekada nesugriauna kitų.

Jei likusi kvota nepadengia visų galiojančių įrašų, atmetamas visas paketas, o ne apdorojamas iš dalies — jums niekada nereikia spėlioti, kur apdorojimas sustojo.

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

Kiekvienas raktas turi 500 patikrų per UTC kalendorinę dieną. Dabartinė būsena keliauja su kiekvienu autentifikuotu atsaku, todėl jai sužinoti niekada nereikia papildomo iškvietimo.

Atmesti iškvietimai taip pat skaičiuojami: klientas, ciklu siuntinėjantis negaliojančias užklausas, apriboja pats save. Kvota nustatoma kiekvienam raktui — parašykite mums, jei reikia daugiau.

Atsakas

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

Klaidos

Klaidų pranešimai yra tik anglų kalba: tai protokolo pranešimai, skirti kūrėjams. Verčiamas tik dalykinis turinys.

Kiekvienas atsakas turi užklausos identifikatorių, pakartotą tekste. Nurodykite jį susisiekdami su mumis — jis nuveda mus tiesiai prie iškvietimo.

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

Būsena	code	Reikšmė
400	invalid_json	Tekstas nėra tinkamas JSON.
422	invalid_request	JSON tinkamas, bet jo turinys ne. Detalės nurodo klaidingą lauką.
401	missing_credentials	Trūksta Authorization antraštės arba ji netaisyklinga.
401	invalid_key	Nežinomas raktas.
401	key_revoked	Panaikintas raktas.
403	account_suspended	Rakto savininko paskyra sustabdyta.
415	unsupported_media_type	Turinio tipas nėra JSON.
413	payload_too_large	Užklausos tekstas per didelis.
429	rate_limit_exceeded	Pasiekta dienos kvota. Žiūrėkite Retry-After antraštę.
500	internal_error	Klaida mūsų pusėje. Bandykite dar kartą ir praneškite mums su užklausos identifikatoriumi.

Duomenys ir saugojimas

Per API atsiųstos bylos yra jūsų klientų duomenys: saugome kuo mažiau, o jūs turite jungiklį nesaugoti nieko.

Siųskite „store“ kaip false ir joks bylos turinys nebus įrašytas: liks tik balas ir neatitikimų kodai.
Priešingu atveju bylų turinys ištrinamas po 30 dienų.
Rakto panaikinimas iškart ištrina juo pateiktų bylų turinį.
Apdorojimas vyksta Frankfurte, o duomenų bazė talpinama Europos Sąjungoje.
Per API failai neįkeliami: jūs tik nurodote, kuriuos dokumentus turite.

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

Kas šis API nėra

Patikra padeda pasirengti. Ji nėra muitinės administracijos patvirtinimas, ji nieko neteikia ir nepakeičia jūsų operacijai taikomų teisinių pareigų.

Muitinės kodai tikrinami dėl formato ir suderinamumo su operacija, niekada nelyginami su tarifų duomenų baze: taisyklingai sudarytas kodas lieka kodu, kurį reikia patikrinti.