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 exponerar valideringsmotorn: tretton tvärgående regler, fyra regler för handlingarnas fullständighet och de validatorer som hör till varje deklarationssystem. Det lämnar inte in något och frågar ingen tulltaxedatabas — det kontrollerar den inre konsistensen och formatet i ditt ärende 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.

1Skapa en nyckel från ditt konto, under ”API-nycklar”.
2Skicka den i Authorization-huvudet i varje begäran.
3Å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": 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 }
}

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

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 mot format och mot samstämmighet med transaktionen, aldrig mot en tulltaxedatabas: en välformad kod är fortfarande en kod att verifiera.