Arendajatele

Tollikontrolli API

Sama kontroll nagu sellel saidil, välja kutsutud teie enda tarkvarast. Saadate toimiku JSON-vormingus ja saate skoori sajast, takistavad punktid, hoiatused ja soovitatud sammud — püsivate kõrvalekallete koodidega ja teadetega Euroopa Liidu 24 ametlikus keeles.

Loo võti OpenAPI spetsifikatsioon

See on serverilt serverile API. API võti on saladus. Brauserist tehtud päringuid ei toetata ja autenditud teedel CORS-päiseid ei saadeta: brauserisse jõudnud võti on lekkinud võti.

Ülevaade

API avab valideerija kontrollimootori: kolmteist läbivat reeglit, neli dokumentide täielikkuse reeglit ja igale deklaratsioonisüsteemile omased valideerijad. See ei edasta midagi ega päri ühestki tariifiandmebaasist — see kontrollib teie toimiku sisemist sidusust ja vormingut enne, kui te deklaratsiooni koostate.

Kõigil teedel on eesliiteks nende versioon. Avastusteed ja spetsifikatsioon on avalikud: integreerija või agent saab skeemi lugeda enne võtme omamist.

Tee	Roll	Autentimine
POST/v1/checks	Kontrollib toimikut ja tagastab täieliku aruande	Võti nõutav
POST/v1/checks/batch	Kontrollib ühe päringuga kuni 25 toimikut	Võti nõutav
GET/v1/me	Tagastab praeguse võtme ja selle kvoodi, seda kulutamata	Võti nõutav
GET/v1/declaration-types	Loetleb tuntud deklaratsiooniliigid	Avalik
GET/v1/declaration-types/{type}	Kirjeldab ühe liigi puhul oodatavaid välju	Avalik
GET/v1/openapi.json	Selle API OpenAPI 3.1 spetsifikatsioon	Avalik

Autentimine

API autendib kandjatunnusega. Tunnust näidatakse vaid korra, loomise hetkel: säilitatakse ainult selle jäljend, seega kaotatud võti asendatakse, mitte kunagi ei taastata.

Korraga võite hoida kolme aktiivset võtit, mis võimaldab võtit vahetada ilma lõimingut katkestamata: looge uus, võtke kasutusele ja seejärel tühistage vana.

1Looge võti oma kontol jaotises „API võtmed“.
2Saatke see iga päringu Authorization-päises.
3Lekke korral tühistage see: katkestus on kohene ja selle võtmega esitatud toimikute sisu kustutatakse otsekohe.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Esimene kontroll

Toimik koosneb liigist, päisest ja kaubaridadest. Kõik väärtused on sõned: nende tõlgendamise eest hoolitseb mootor. Väljade nimed selguvad käitusajal, liik liigi haaval.

Vastus saabub kohe; pärast seda pole midagi pärida.

Päring

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

Vastuse lugemine

Iga kõrvalekalle kannab korraga masinidentiteeti ja loetavat lauset. Ehitage oma loogika masinidentiteedile: see ei muutu ilma versioonivahetuseta.

severity · code · path · rule: Püsiv lepingPüsivad. Uusi koode võib lisanduda; olemasolevaid ei nimetata ümber ilma versioonivahetuseta.
field · message · text: Ainult kuvamiseksTõlgitud kuvamiseks. Neid võidakse igal ajal ümber sõnastada — ärge kunagi võrrelge neid oma koodis.
engine.version: Muutub niipea, kui reeglimuudatus nihutab muutumatu toimiku skoori. Arhiveerige see koos oma aruannetega.

Väli „path“ peegeldab teie päringu kuju, nii et saate kõrvalekalde siduda otse vastava väljaga oma liideses.

header.<väli> · items.<n>.<väli> · documents.<category> · global

Vastus

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

Väljade avastamine

Deklaratsiooniliigid ja nende väljad on avalikud, võtit pole vaja. See on tee vormi koostamiseks, ERP-st pärineva vastenduse toitmiseks või skeemi andmiseks agendile, kes peab selle täitma.

Siin tagastatud nimed on täpselt need võtmed, mida kasutada päises ja igal kaubareal. Valikuloendid tulevad lahendatult ja tõlgitult; lisage parameeter nende ärajätmiseks, kui vastus tundub liiga mahukas.

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

Pakktöötlus

Kuni 25 toimikut päringu kohta. Vastus on alati edukas, kui pakk on vastu võetud, ja iga kirje kannab oma olekut: üks vigane toimik ei kukuta kunagi teisi läbi.

Kui järelejäänud kvoot ei kata kõiki kehtivaid kirjeid, lükatakse tagasi kogu pakk, mitte ei töödelda seda osaliselt — te ei pea kunagi arvama, kus töötlus peatus.

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

Kvoot

Igal võtmel on 500 kontrolli UTC kalendripäeva kohta. Praegune seis rändab kaasa iga autenditud vastusega, seega ei vaja te selle teadasaamiseks kunagi lisapäringut.

Ka tagasi lükatud päringud lähevad arvesse: klient, kes tsükleldab kehtetute päringutega, piirab iseennast. Kvoot on seatud võtme kohta — kirjutage meile, kui vajate rohkem.

Vastus

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

Vead

Veateated on ainult inglise keeles: need on protokolliteated, mõeldud arendajatele. Tõlgitakse ainult sisuline osa.

Iga vastus kannab päringu tunnust, mida korratakse kehas. Viidake sellele meiega ühendust võttes — see viib meid otse selle päringuni.

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

Olek	code	Tähendus
400	invalid_json	Keha ei ole kehtiv JSON.
422	invalid_request	JSON on kehtiv, kuid selle sisu mitte. Üksikasjad nimetavad vigase välja.
401	missing_credentials	Authorization-päis puudub või on vigane.
401	invalid_key	Tundmatu võti.
401	key_revoked	Tühistatud võti.
403	account_suspended	Võtme omanikukonto on peatatud.
415	unsupported_media_type	Sisutüüp ei ole JSON.
413	payload_too_large	Päringu keha on liiga suur.
429	rate_limit_exceeded	Päevane kvoot on täis. Vaadake Retry-After päist.
500	internal_error	Viga meie poolel. Proovige uuesti ja teatage meile päringu tunnusega.

Andmed ja säilitamine

API kaudu saadetud toimikud on teie klientide andmed: säilitame võimalikult vähe ja teil on lüliti, et mitte midagi ei säilitataks.

Saatke „store“ väärtusega false ja toimiku sisu ei kirjutata üldse: alles jäävad vaid skoor ja kõrvalekallete koodid.
Vastasel juhul kustutatakse toimikute sisu 30 päeva pärast.
Võtme tühistamine kustutab kohe sellega esitatud toimikute sisu.
Töötlus toimub Frankfurdis ja andmebaas asub Euroopa Liidus.
API kaudu faile üles ei laadita: te üksnes märgite, millised dokumendid teil on.

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

Mis see API ei ole

Kontroll aitab ettevalmistusel. See ei ole tolliameti kinnitus, see ei esita midagi ega asenda teie tehingule kohalduvaid õigusnõudeid.

Tollikoode kontrollitakse vormingu ja tehinguga sidususe osas, mitte kunagi tariifiandmebaasi vastu: korrektselt vormistatud kood jääb koodiks, mida tuleb kontrollida.