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 tuo saataville tarkistimen moottorin: kolmetoista läpileikkaavaa sääntöä, neljä asiakirjojen täydellisyyden sääntöä ja kunkin ilmoitusjärjestelmän omat tarkistimet. Se ei lähetä mitään eikä kysele mistään tariffitietokannasta — se tarkistaa asiakirjasi sisäisen johdonmukaisuuden ja muodon ennen kuin valmistelet 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.

1Luo avain tililtäsi kohdasta ”API-avaimet”.
2Lähetä se jokaisen pyynnön Authorization-otsakkeessa.
3Peruuta 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": 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 }
}

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

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 ja toimeen sopivuuden osalta, ei koskaan tariffitietokantaa vasten: hyvin muodostettu koodi on yhä tarkistettava koodi.