Kehittäjille

Tullitarkistuksen API

Sama tarkistus kuin tällä sivustolla, kutsuttuna omasta ohjelmistostasi. Lähetät asiakirjan JSON-muodossa ja saat pistemäärän sadasta, estävät kohdat, varoitukset ja suositellut toimet — vakain poikkeamakoodein ja viestein Euroopan unionin 24 virallisella kielellä.

Luo avain OpenAPI-määrittely

Tämä on palvelimelta palvelimelle -API. API-avain on salaisuus. Selaimesta tehtyjä kutsuja ei tueta, eikä tunnistetuilla reiteillä lähetetä CORS-otsakkeita: selaimeen päätyvä avain on vuotanut avain.

Yleiskuva

API tarjoaa tarkistimen tarkistusmoottorin: neljätoista yleistä sääntöä, viisi TARIC-sääntöä, neljä asiakirjojen täydellisyyttä koskevaa sääntöä ja kunkin ilmoitusjärjestelmän omat tarkistukset. Se ei lähetä mitään: se tarkistaa asiakirjojesi muodon ja johdonmukaisuuden, koodien olemassaolon nimikkeistössä sekä EU:hun tuotaessa alkuperään sovellettavat TARIC-toimenpiteet (polkumyynti, valvonta, etuudet, tulli), ennen kuin laadit ilmoituksen.

Jokaisella reitillä on versionsa etuliitteenä. Löytöreitit ja määrittely ovat julkisia: integroija tai agentti voi lukea skeeman jo ennen avaimen hankkimista.

Reitti	Tehtävä	Tunnistautuminen
POST/v1/checks	Tarkistaa asiakirjan ja palauttaa täyden raportin	Avain vaaditaan
POST/v1/checks/batch	Tarkistaa enintään 25 asiakirjaa yhdellä kutsulla	Avain vaaditaan
GET/v1/me	Palauttaa nykyisen avaimen ja sen kiintiön kuluttamatta sitä	Avain vaaditaan
GET/v1/declaration-types	Luettelee tunnistetut ilmoitustyypit	Julkinen
GET/v1/declaration-types/{type}	Kuvaa yhden tyypin odotetut kentät	Julkinen
GET/v1/openapi.json	Tämän API:n OpenAPI 3.1 -määrittely	Julkinen

Tunnistautuminen

API tunnistautuu bearer-tunnuksella. Tunnus näytetään vain kerran, luonnin yhteydessä: siitä tallennetaan vain tiiviste, joten kadonnut avain korvataan, ei koskaan palauteta.

Voit pitää kolme aktiivista avainta kerrallaan, jolloin voit vaihtaa avaimen keskeyttämättä integraatiotasi: luo uusi, ota se käyttöön ja peruuta sitten vanha.

01Luo avain tililtäsi kohdasta ”API-avaimet”.
02Lähetä se jokaisen pyynnön Authorization-otsakkeessa.
03Peruuta se vuodon sattuessa: katkaisu on välitön, ja kyseisellä avaimella lähetettyjen asiakirjojen sisältö poistetaan heti.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ensimmäinen tarkistus

Asiakirja koostuu tyypistä, otsikosta ja tavarariveistä. Kaikki arvot ovat merkkijonoja: moottori hoitaa niiden tulkinnan. Kenttien nimet selviävät ajonaikana, tyyppi kerrallaan.

Vastaus tulee heti; sen jälkeen ei ole mitään kyseltävää.

Pyyntö

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

Vastauksen lukeminen

Jokainen poikkeama kantaa sekä koneellisen tunnisteen että luettavan lauseen. Rakenna logiikkasi koneellisen tunnisteen varaan: se ei muutu ilman versionvaihtoa.

severity · code · path · rule: Vakaa sopimusVakaita. Uusia koodeja voi ilmestyä; olemassa olevia ei nimetä uudelleen ilman versionvaihtoa.
field · message · text: Vain näyttöönKäännetty näyttöä varten. Ne voidaan muotoilla uudelleen milloin tahansa — älä koskaan vertaa niitä koodissasi.
engine.version: Muuttuu heti, kun sääntömuutos siirtää muuttumattoman asiakirjan pistemäärää. Arkistoi se raporttiesi mukana.

Kenttä ”path” noudattaa pyyntösi rakennetta, joten voit kytkeä poikkeaman suoraan omassa käyttöliittymässäsi olevaan kenttään.

header.<kenttä> · items.<n>.<kenttä> · documents.<category> · global

Vastaus

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

Kenttien löytäminen

Ilmoitustyypit ja niiden kentät ovat julkisia, avainta ei tarvita. Tämä on reitti lomakkeen rakentamiseen, kartoituksen syöttämiseen toiminnanohjauksestasi tai skeeman antamiseen agentille täytettäväksi.

Täältä palautuvat nimet ovat täsmälleen ne avaimet, joita käytetään otsikossa ja kullakin tavararivillä. Valintalistat palautuvat ratkaistuina ja käännettyinä; lisää parametri jättääksesi ne pois, jos vastaus tuntuu raskaalta.

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

Eräajo

Enintään 25 asiakirjaa kutsua kohti. Vastaus on aina onnistuminen heti kun erä on hyväksytty, ja jokainen merkintä kantaa oman tilansa: yksi virheellinen asiakirja ei koskaan kaada muita.

Jos jäljellä oleva kiintiö ei kata kaikkia kelvollisia merkintöjä, koko erä hylätään sen sijaan, että se käsiteltäisiin osittain — sinun ei koskaan tarvitse arvailla, mihin käsittely pysähtyi.

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

Agentit ja työkalut

REST-reittien lisäksi sama moottori ja samat tiedot ovat käytettävissä tekoälyavustajasta Model Context Protocol (MCP) -palvelimen kautta ja API-asiakkaasta valmiin Postman-kokoelman kautta. Molemmat käyttävät edellä kuvattua API-avainta ja päivittäistä kiintiötä.

MCP-palvelin

MCP-palvelimen avulla avustaja voi hakea tullikoodeja, lukea koodin EU:n tuontitullin, tarkistaa EORI-, ALV- tai AEO-numeron virallisista rekistereistä ja tarkistaa ilmoitusluonnoksen ilman, että kirjoitat riviäkään liitoskoodia. Se vastaa osoitteessa POST /api/mcp JSON-vastauksin.

Se on tilaton ja puhuu protokollan molempia sukupolvia: versiota 2026-07-28, jossa jokainen pyyntö kantaa versionsa, sekä aiempia versioita, jotka alkavat initialize-kutsulla. Yhteys, havaitseminen ja työkalujen luettelointi ovat ilmaisia; jokainen työkalukutsu kuluttaa yhden yksikön avaimen päiväkiintiöstä.

Todennus on sama bearer-tunniste kuin REST-rajapinnassa. Asiakas, joka tukee vain OAuth-kirjautumista, kuten claude.ai:n verkkoliittimet, ei voi vielä yhdistää: käytä asiakasta, jossa voi asettaa otsakkeen.

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	Tarkista ilmoitusluonnos: pistemäärä sadasta, taso ja jokainen ongelma kenttineen ja toimenpiteineen. Ei säilytä tiedoston sisältöä, ellei sitä pyydetä.
list_declaration_types	Tuetut ilmoitusjärjestelmät viranomaisineen, alueineen ja odotettuine asiakirjoineen.
describe_declaration_type	Tyypin otsikko- ja nimikekentät check_declaration-syötteen rakentamiseksi.
search_hs_codes	Yhdistetyn nimikkeistön ehdokaskoodit tuotekuvauksesta millä tahansa EU:n 24 kielestä.
describe_hs_code	Onko 4–10-numeroinen koodi voimassa olevassa nimikkeistössä, virallisine polkuineen ja sanamuotoineen.
lookup_import_duty	Koodin EU:n tuontitulli komission TARIC-tietojen perusteella: kolmansien maiden tulli, alkuperäsoveltuvat etuudet, kiintiöt, polkumyynnin vastaiset toimet ja valvonta.
search_chemical	Kemiallinen aine CAS-numerolla, CUS-numerolla tai nimellä komission ECICS-luettelosta: kullekin merkinnälle annettu yhdistetyn nimikkeistön koodi, tarkistettavaksi.
get_quota_balance	EU:n tariffikiintiön jäljellä oleva saldo komission QUOTA-tietokannassa järjestysnumeron tai koodin ja alkuperän perusteella: saldo, tila (avoin, kriittinen, estetty, käytetty loppuun), jakso ja lukuhetki.
validate_eori	EORI-numeron muoto ja sen tila virallisessa rekisterissä (Euroopan komissio, HMRC).
validate_vat	EU:n ALV-tunnisteen muoto ja sen voimassaolo VIES-järjestelmässä sekä rekisteröity nimi, jos se on julkaistu.
check_rex	Rekisteröidyn viejän REX-numeron muoto ja sen tila komission REX-tietokannassa (voimassa, peruutettu tai tuntematon) päivämäärineen.
screen_sanctions	Yritys, henkilö tai alus EU:n, YK:n, Yhdistyneen kuningaskunnan ja Yhdysvaltojen pakoteluetteloja vasten, päivitetään päivittäin: jokainen osuma pisteineen, vahva tai osittainen.
search_aeo	Haku komission valtuutettujen talouden toimijoiden tietokannasta yrityksen nimen perusteella.

Tullikoodit ovat nimikkeistön sanamuodosta johdettuja ehdotuksia. Luokituksen voi vahvistaa vain ilmoittaja tai tullin sitova tariffitieto.
Tullit ovat suuntaa-antavia: ehtoja, maakohtaisia poikkeuksia ja loppuun käytettyjä kiintiöitä ei arvioida. Jokaisessa vastauksessa on TARIC-otteen viitepäivä, joka päivitetään kuukausittain.
Rekisteri, joka ei vastaa, ilmoitetaan ei-saatavilla olevaksi, ei koskaan virheellisenä numerona. Tullille ei koskaan lähetetä mitään.

Postman-kokoelma

Kokoelma luodaan OpenAPI-määrittelystä, joten se vastaa sitä aina: yksi pyyntö reittiä kohti, tunnisteen mukaan ryhmiteltynä, jokaiselle POST-pyynnölle rungon pohja. Tuo se Postmaniin, täytä muuttuja apiKey (säilytetään salaisena), ja pyynnöt ovat valmiita lähetettäviksi.

Lataa kokoelma

Kiintiö

Jokaisella avaimella on 500 tarkistusta UTC-kalenterivuorokautta kohti. Nykyinen tila kulkee jokaisen tunnistetun vastauksen mukana, joten et koskaan tarvitse ylimääräistä kutsua sen lukemiseen.

Myös hylätyt kutsut lasketaan: asiakas, joka jauhaa virheellisiä pyyntöjä, kuristaa itsensä. Kiintiö asetetaan avainkohtaisesti — kirjoita meille, jos tarvitset enemmän.

Vastaus

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

Virheet

Virheilmoitukset ovat vain englanniksi: ne ovat protokollaviestejä kehittäjille. Vain asiasisältö käännetään.

Jokainen vastaus kantaa pyyntötunnuksen, joka toistetaan rungossa. Mainitse se ottaessasi meihin yhteyttä — se vie meidät suoraan kyseiseen kutsuun.

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

Tila	code	Merkitys
400	invalid_json	Runko ei ole kelvollista JSONia.
422	invalid_request	JSON on kelvollista, mutta sen sisältö ei. Yksityiskohdat nimeävät virheellisen kentän.
401	missing_credentials	Authorization-otsake puuttuu tai on virheellinen.
401	invalid_key	Tuntematon avain.
401	key_revoked	Peruutettu avain.
403	account_suspended	Avaimen omistava tili on jäädytetty.
415	unsupported_media_type	Sisältötyyppi ei ole JSON.
413	payload_too_large	Pyynnön runko on liian suuri.
429	rate_limit_exceeded	Päivittäinen kiintiö täynnä. Katso Retry-After-otsake.
500	internal_error	Virhe meidän päässämme. Yritä uudelleen ja ilmoita siitä pyyntötunnuksen kanssa.

Tiedot ja säilytys

API:n kautta lähetetyt asiakirjat ovat asiakkaidesi tietoja: säilytämme mahdollisimman vähän, ja sinulla on kytkin olla säilyttämättä mitään.

Lähetä ”store” arvolla false, niin mitään asiakirjan sisältöä ei kirjoiteta: vain pistemäärä ja poikkeamakoodit säilyvät.
Muutoin asiakirjojen sisältö poistetaan 30 päivän kuluttua.
Avaimen peruuttaminen poistaa välittömästi sillä lähetettyjen asiakirjojen sisällön.
Käsittely tapahtuu Frankfurtissa ja tietokanta sijaitsee Euroopan unionissa.
API:n kautta ei ladata tiedostoja: ilmoitat vain, mitkä asiakirjat sinulla on.

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

Mitä tämä API ei ole

Tarkistus auttaa valmistelussa. Se ei ole tulliviranomaisen hyväksyntä, se ei jätä mitään, eikä se korvaa toimeesi sovellettavia säädösvelvoitteita.

Tullikoodit tarkistetaan muodon, nimikkeistössä olemassaolon ja EU:hun tuotaessa niiden alkuperää koskevien TARIC-toimenpiteiden osalta, ei koskaan tavaran luokittelun osalta: olemassa oleva koodi on edelleen tarkistettava koodi. TARIC-toimenpiteet ovat suuntaa antavia (Euroopan komission kuukausittainen poiminta): maapoikkeuksia, käytettyjä kiintiöitä ja ehdollisia tulleja ei arvioida.