Udviklere

API til toldkontrol

Samme kontrol som på dette site, kaldt fra din egen software. Du sender en sag som JSON og får en score ud af 100, de blokerende punkter, advarslerne og de anbefalede handlinger — med stabile afvigelseskoder og beskeder på EU's 24 officielle sprog.

Opret en nøgle OpenAPI-specifikation

Dette er en server-til-server-API. En API-nøgle er en hemmelighed. Kald fra en browser understøttes ikke, og der sendes ingen CORS-headere på godkendte ruter: en nøgle, der havner i en browser, er en lækket nøgle.

Overblik

API'et eksponerer validatorens kontrolmotor: tretten tværgående regler, fire regler om dokumenternes fuldstændighed og de validatorer, der hører til hvert angivelsessystem. Det indsender intet og forespørger ingen tarifdatabase — det kontrollerer den indre sammenhæng og formatet af din sag, før du udarbejder angivelsen.

Alle ruter har deres version som præfiks. Opdagelsesruterne og specifikationen er offentlige: en integrator eller en agent kan læse skemaet, før vedkommende har en nøgle.

Rute	Rolle	Godkendelse
POST/v1/checks	Kontrollerer en sag og returnerer den fulde rapport	Nøgle påkrævet
POST/v1/checks/batch	Kontrollerer op til 25 sager i ét kald	Nøgle påkrævet
GET/v1/me	Returnerer den aktuelle nøgle og dens kvote uden at bruge af den	Nøgle påkrævet
GET/v1/declaration-types	Viser de angivelsestyper, der genkendes	Offentlig
GET/v1/declaration-types/{type}	Beskriver de felter, der forventes for en type	Offentlig
GET/v1/openapi.json	OpenAPI 3.1-specifikationen for dette API	Offentlig

Godkendelse

API'et godkender med et bearer-token. Tokenet vises kun én gang, ved oprettelsen: kun aftrykket gemmes, så en mistet nøgle erstattes, aldrig genskabes.

Du kan have tre aktive nøgler ad gangen, så du kan rotere en nøgle uden at afbryde din integration: opret den nye, rul den ud, og tilbagekald derefter den gamle.

1Opret en nøgle fra din konto under „API-nøgler“.
2Send den i Authorization-headeren i hver anmodning.
3Tilbagekald den ved lækage: afbrydelsen er øjeblikkelig, og indholdet af de sager, der er indsendt med nøglen, slettes med det samme.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Første kontrol

En sag består af en type, et hoved og varelinjer. Alle værdier er tekststrenge: motoren står for at fortolke dem. Feltnavnene opdages ved kørsel, type for type.

Svaret kommer med det samme; der er intet at spørge om bagefter.

Anmodning

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

At læse svaret

Hver afvigelse bærer både en maskinidentitet og en læsbar sætning. Byg din logik på maskinidentiteten: den ændrer sig ikke uden et versionsskift.

severity · code · path · rule: Stabil kontraktStabile. Nye koder kan komme til; eksisterende omdøbes ikke uden et versionsskift.
field · message · text: Kun visningOversat til visning. De kan omformuleres når som helst — sammenlign dem aldrig i din kode.
engine.version: Ændrer sig, så snart en regelændring flytter scoren for en uændret sag. Arkivér den sammen med dine rapporter.

Feltet „path“ spejler formen på din anmodning, så du kan knytte en afvigelse direkte til det tilsvarende felt i din egen grænseflade.

header.<felt> · items.<n>.<felt> · 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 }
}

Opdag felterne

Angivelsestyper og deres felter er offentlige, og der kræves ingen nøgle. Det er ruten til at bygge en formular, fodre en mapning fra dit ERP eller give en agent det skema, den skal udfylde.

Navnene her er præcis de nøgler, der skal bruges i hovedet og i hver varelinje. Valglister returneres opslåede og oversatte; tilføj parameteren for at udelade dem, hvis svaret virker 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"

Batchbehandling

Op til 25 sager pr. kald. Svaret er altid en succes, når batchen er accepteret, og hver post bærer sin egen status: én misdannet sag får aldrig de andre til at fejle.

Dækker den resterende kvote ikke alle gyldige poster, afvises hele batchen frem for at blive delvist behandlet — du skal aldrig gætte, hvor behandlingen stoppede.

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

Kvote

Hver nøgle har 500 kontroller pr. UTC-kalenderdag. Den aktuelle status følger med hvert godkendt svar, så du behøver aldrig et ekstra kald for at kende den.

Afviste kald tæller også med: en klient, der kører i ring på ugyldige anmodninger, bremser sig selv. Kvoten fastsættes pr. nøgle — skriv til os, hvis du har brug for mere.

Svar

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

Fejl

Fejlbeskeder er kun på engelsk: det er protokolbeskeder henvendt til udviklere. Kun det faglige indhold er oversat.

Hvert svar bærer et anmodnings-id, der gentages i brødteksten. Angiv det, når du kontakter os — det fører os direkte til kaldet.

{
  "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	Betydning
400	invalid_json	Brødteksten er ikke gyldig JSON.
422	invalid_request	JSON er gyldig, men indholdet er ikke. Detaljerne udpeger det fejlbehæftede felt.
401	missing_credentials	Authorization-header mangler eller er misdannet.
401	invalid_key	Ukendt nøgle.
401	key_revoked	Tilbagekaldt nøgle.
403	account_suspended	Kontoen bag nøglen er suspenderet.
415	unsupported_media_type	Indholdstypen er ikke JSON.
413	payload_too_large	Anmodningens brødtekst er for stor.
429	rate_limit_exceeded	Daglig kvote nået. Se Retry-After-headeren.
500	internal_error	En fejl hos os. Prøv igen, og meld den til os med anmodnings-id'et.

Data og opbevaring

Sager sendt via API'et er dine kunders data: vi gemmer så lidt som muligt, og du har en kontakt til slet ikke at gemme noget.

Send „store“ som false, og intet sagsindhold skrives: kun scoren og afvigelseskoderne bevares.
Ellers slettes sagsindholdet efter 30 dage.
At tilbagekalde en nøgle sletter straks indholdet af de sager, den har indsendt.
Behandlingen sker i Frankfurt, og databasen er hostet i Den Europæiske Union.
Ingen fil uploades via API'et: du oplyser kun, hvilke dokumenter du har.

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

Hvad dette API ikke er

Kontrollen hjælper med forberedelsen. Den udgør ikke en godkendelse fra toldmyndighederne, den indsender intet, og den erstatter ikke de regler, der gælder for din transaktion.

Toldkoder kontrolleres for format og sammenhæng med transaktionen, aldrig mod en tarifdatabase: en velformet kode er stadig en kode, der skal verificeres.