Utvecklare

API för tullkontroll

Samma kontroll som på den här webbplatsen, anropad från din egen programvara. Du skickar ett ärende som JSON och får en poäng av 100, de blockerande punkterna, varningarna och de rekommenderade åtgärderna — med stabila avvikelsekoder och meddelanden på EU:s 24 officiella språk.

Skapa en nyckel OpenAPI-specifikation

Det här är ett server-till-server-API. En API-nyckel är en hemlighet. Anrop från en webbläsare stöds inte och inga CORS-huvuden skickas på autentiserade rutter: en nyckel som hamnar i en webbläsare är en läckt nyckel.

Översikt

API:et ger tillgång till validerarens kontrollmotor: fjorton övergripande regler, fem Taric-regler, fyra regler om fullständiga dokument och de validerare som hör till varje deklarationssystem. Det skickar ingenting: det kontrollerar format och samstämmighet i ditt ärende, att koderna finns i nomenklaturen och, vid import till EU, de Taric-åtgärder som gäller för ursprunget (antidumpning, kontroller, förmåner, tullsats), innan du förbereder deklarationen.

Alla rutter har sin version som prefix. Upptäcktsrutterna och specifikationen är öppna: en integratör eller en agent kan läsa schemat innan den har en nyckel.

Rutt	Roll	Autentisering
POST/v1/checks	Kontrollerar ett ärende och returnerar hela rapporten	Nyckel krävs
POST/v1/checks/batch	Kontrollerar upp till 25 ärenden i ett anrop	Nyckel krävs
GET/v1/me	Returnerar aktuell nyckel och dess kvot, utan att förbruka den	Nyckel krävs
GET/v1/declaration-types	Listar de deklarationstyper som känns igen	Öppen
GET/v1/declaration-types/{type}	Beskriver de fält som förväntas för en typ	Öppen
GET/v1/openapi.json	OpenAPI 3.1-specifikationen för detta API	Öppen

Autentisering

API:et autentiserar med en bearer-token. Token visas bara en gång, vid skapandet: endast dess avtryck sparas, så en förlorad nyckel ersätts, aldrig återskapas.

Du kan ha tre aktiva nycklar samtidigt, vilket låter dig rotera en nyckel utan att avbryta din integration: skapa den nya, rulla ut den och återkalla sedan den gamla.

01Skapa en nyckel från ditt konto, under ”API-nycklar”.
02Skicka den i Authorization-huvudet i varje begäran.
03Återkalla den vid läcka: avbrottet sker omedelbart och innehållet i de ärenden som skickats med nyckeln rensas direkt.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Första kontrollen

Ett ärende består av en typ, ett huvud och varurader. Alla värden är strängar: motorn sköter tolkningen. Fältnamnen upptäcks vid körning, typ för typ.

Svaret kommer direkt; det finns inget att fråga efter i efterhand.

Begäran

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

Att läsa svaret

Varje avvikelse bär både en maskinidentitet och en läsbar mening. Bygg din logik på maskinidentiteten: den ändras inte utan ett versionsbyte.

severity · code · path · rule: Stabilt kontraktStabila. Nya koder kan tillkomma; befintliga byter inte namn utan ett versionsbyte.
field · message · text: Endast visningÖversatta för visning. De kan omformuleras när som helst — jämför dem aldrig i din kod.
engine.version: Ändras så snart en regeländring flyttar poängen för ett oförändrat ärende. Arkivera den tillsammans med dina rapporter.

Fältet ”path” speglar formen på din begäran, så att du kan koppla en avvikelse direkt till motsvarande fält i ditt eget gränssnitt.

header.<fält> · items.<n>.<fält> · documents.<category> · global

Svar

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

Upptäck fälten

Deklarationstyper och deras fält är öppna, ingen nyckel behövs. Det är rutten för att bygga ett formulär, mata en mappning från ditt affärssystem eller ge en agent schemat den ska fylla i.

Namnen som returneras här är exakt de nycklar som ska användas i huvudet och i varje varurad. Alternativlistor returneras upplösta och översatta; lägg till parametern för att utelämna dem om svaret känns tungt.

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

Satsvis behandling

Upp till 25 ärenden per anrop. Svaret är alltid en framgång så snart satsen accepterats, och varje post bär sin egen status: ett felformat ärende fäller aldrig de andra.

Om den återstående kvoten inte täcker alla giltiga poster avvisas hela satsen i stället för att behandlas delvis — du behöver aldrig gissa var behandlingen stannade.

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

Agenter och verktyg

Förutom REST-vägarna kan samma motor och samma data nås från en AI-assistent, via en Model Context Protocol-server (MCP), och från en API-klient, via en färdig Postman-samling. Båda använder API-nyckeln och den dagliga kvoten som beskrivs ovan.

MCP-server

MCP-servern låter en assistent slå upp tullkoder, läsa EU:s importtull för en kod, kontrollera ett EORI-, moms- eller AEO-nummer i de officiella registren och kontrollera ett deklarationsutkast, utan att du skriver en enda rad bindningskod. Den svarar på POST /api/mcp, med JSON-svar.

Den är tillståndslös och talar båda generationerna av protokollet: revisionen 2026-07-28, där varje förfrågan bär sin version, och de tidigare revisionerna, som inleds med ett initialize-anrop. Anslutning, upptäckt och listning av verktygen kostar ingenting; varje verktygsanrop förbrukar en enhet av nyckelns dagliga kvot.

Autentiseringen är samma bearer-token som i REST-API:et. En klient som bara stöder OAuth-inloggning, som claude.ai:s webbkopplingar, kan ännu inte ansluta: använd en klient där du kan ange en header.

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	Kontrollera ett deklarationsutkast: poäng av 100, nivå och varje problem med fältet och åtgärden. Sparar inte filens innehåll om det inte begärs.
list_declaration_types	De deklarationssystem som stöds, med myndighet, region och förväntade handlingar.
describe_declaration_type	Huvud- och varufälten för en typ, för att bygga indata till check_declaration.
search_hs_codes	Kandidatkoder i den kombinerade nomenklaturen utifrån en varubeskrivning, på något av EU:s 24 språk.
describe_hs_code	Om en kod på 4 till 10 siffror finns i den gällande nomenklaturen, med dess officiella sökväg och lydelse.
lookup_import_duty	EU:s importtull för en kod ur kommissionens TARIC-data: tull för tredjeland, preferenser för ett ursprung, kvoter, antidumpning och kontroller.
search_chemical	Ett kemiskt ämne efter CAS-nummer, CUS-nummer eller namn i kommissionens ECICS-förteckning: den kod i kombinerade nomenklaturen som anges för varje post, att kontrollera.
get_quota_balance	Återstående saldo för en EU-tullkvot i kommissionens QUOTA-databas, utifrån löpnumret eller en kod och ett ursprung: saldo, tillstånd (öppen, kritisk, blockerad, förbrukad), period och tidpunkt för avläsningen.
validate_eori	Formatet på ett EORI-nummer och dess status i det officiella registret (Europeiska kommissionen, HMRC).
validate_vat	Formatet på ett EU-momsnummer och dess giltighet i VIES, med det registrerade namnet där det publiceras.
check_rex	Formatet på ett REX-nummer för en registrerad exportör och dess status i kommissionens REX-databas (giltigt, återkallat eller okänt), med datum.
screen_sanctions	Ett företag, en person eller ett fartyg mot sanktionslistorna från EU, FN, Storbritannien och USA, uppdaterade varje dag: varje träff med sin poäng, stark eller partiell.
search_aeo	Sök i kommissionens databas över godkända ekonomiska operatörer på företagsnamn.

Tullkoder är förslag hämtade ur nomenklaturens lydelse. Bara deklaranten, eller ett bindande klassificeringsbesked från tullen, kan bekräfta en klassificering.
Tullsatser är vägledande: villkor, landsundantag och förbrukade kvoter utvärderas inte. Varje svar bär referensdatumet för TARIC-utdraget, som uppdateras varje månad.
Ett register som inte svarar rapporteras som otillgängligt, aldrig som ett ogiltigt nummer. Ingenting skickas någonsin till tullen.

Postman-samling

Samlingen genereras ur OpenAPI-specifikationen och stämmer därför alltid överens med den: en förfrågan per väg, grupperade efter tagg, med ett body-skelett för varje POST. Importera den i Postman, fyll i variabeln apiKey (sparad som hemlighet) så är förfrågningarna redo att skickas.

Ladda ned samlingen

Kvot

Varje nyckel har 500 kontroller per UTC-kalenderdag. Aktuell status följer med varje autentiserat svar, så du behöver aldrig ett extra anrop för att läsa den.

Avvisade anrop räknas också: en klient som loopar på ogiltiga begäranden strypar sig själv. Kvoten sätts per nyckel — skriv till oss om du behöver mer.

Svar

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

Fel

Felmeddelanden finns bara på engelska: de är protokollmeddelanden riktade till utvecklare. Endast sakinnehållet översätts.

Varje svar bär ett begärans-id som upprepas i kroppen. Ange det när du kontaktar oss — det leder oss rakt till anropet.

{
  "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	Betydelse
400	invalid_json	Kroppen är inte giltig JSON.
422	invalid_request	JSON är giltig men innehållet är det inte. Detaljerna pekar ut det felaktiga fältet.
401	missing_credentials	Authorization-huvudet saknas eller är felformat.
401	invalid_key	Okänd nyckel.
401	key_revoked	Återkallad nyckel.
403	account_suspended	Kontot som äger nyckeln är avstängt.
415	unsupported_media_type	Innehållstypen är inte JSON.
413	payload_too_large	Begärans kropp är för stor.
429	rate_limit_exceeded	Dagskvoten är nådd. Se Retry-After-huvudet.
500	internal_error	Ett fel hos oss. Försök igen och rapportera det med begärans-id:t.

Data och lagring

Ärenden som skickas via API:et är dina kunders data: vi sparar så lite som möjligt, och du har en strömbrytare för att inte spara något alls.

Skicka ”store” som false så skrivs inget ärendeinnehåll alls: bara poängen och avvikelsekoderna bevaras.
Annars rensas ärendeinnehållet efter 30 dagar.
Att återkalla en nyckel rensar omedelbart innehållet i de ärenden den skickat in.
Behandlingen sker i Frankfurt och databasen ligger i Europeiska unionen.
Ingen fil laddas upp via API:et: du anger bara vilka handlingar du har.

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

Vad detta API inte är

Kontrollen hjälper dig att förbereda. Den utgör ingen validering från tullmyndigheten, den lämnar inte in något och den ersätter inte de regelkrav som gäller för din transaktion.

Tullkoder kontrolleras för format, för att de finns i nomenklaturen och, vid import till EU, mot Taric-åtgärderna för deras ursprung, aldrig för klassificeringen av varan: en befintlig kod är fortfarande en kod att verifiera. Taric-åtgärderna är vägledande (månatligt uttag från Europeiska kommissionen): landundantag, uttömda kvoter och villkorade tullar bedöms inte.