Ontwikkelaars

API voor douanecontrole

Dezelfde controle als op deze site, aangeroepen vanuit uw eigen software. U stuurt een dossier als JSON en ontvangt een score op 100, de blokkerende punten, de waarschuwingen en de aanbevolen acties — met stabiele afwijkingscodes en berichten in de 24 officiële talen van de Europese Unie.

Sleutel aanmaken OpenAPI-specificatie

Dit is een server-naar-server-API. Een API-sleutel is een geheim. Aanroepen vanuit een browser worden niet ondersteund en er worden geen CORS-headers verzonden op geauthenticeerde routes: een sleutel die in een browser belandt, is een gelekte sleutel.

Overzicht

De API stelt de controle-engine van de validator beschikbaar: veertien overkoepelende regels, vijf TARIC-regels, vier regels voor volledigheid van documenten en de validators van elk aangiftesysteem. Ze verstuurt niets: ze controleert het formaat en de samenhang van uw dossier, of de codes in de nomenclatuur bestaan en, bij invoer in de EU, de TARIC-maatregelen die voor de oorsprong gelden (antidumping, controles, preferenties, tarief), voordat u de aangifte voorbereidt.

Elke route draagt haar versie als prefix. De ontdekkingsroutes en de specificatie zijn openbaar: een integrator of een agent kan het schema lezen nog vóór hij een sleutel heeft.

Route	Rol	Authenticatie
POST/v1/checks	Controleert een dossier en geeft het volledige rapport terug	Sleutel vereist
POST/v1/checks/batch	Controleert tot 25 dossiers in één aanroep	Sleutel vereist
GET/v1/me	Geeft de huidige sleutel en haar quotum terug, zonder het te verbruiken	Sleutel vereist
GET/v1/declaration-types	Somt de herkende aangiftetypes op	Openbaar
GET/v1/declaration-types/{type}	Beschrijft de verwachte velden voor één type	Openbaar
GET/v1/openapi.json	De OpenAPI 3.1-specificatie van deze API	Openbaar

Authenticatie

De API authenticeert met een bearer-token. Het token wordt slechts eenmaal getoond, bij het aanmaken: alleen de hash wordt bewaard, dus een verloren sleutel wordt vervangen, nooit teruggehaald.

U kunt drie actieve sleutels tegelijk hebben, waardoor u een sleutel kunt roteren zonder uw integratie te onderbreken: maak de nieuwe aan, rol hem uit en trek de oude in.

01Maak een sleutel aan vanuit uw account, onder “API-sleutels”.
02Stuur hem mee in de Authorization-header van elk verzoek.
03Trek hem in bij een lek: de onderbreking is onmiddellijk en de inhoud van de met die sleutel ingediende dossiers wordt meteen gewist.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Eerste controle

Een dossier bestaat uit een type, een kop en goederenregels. Alle waarden zijn tekenreeksen: de motor zorgt voor de interpretatie. De veldnamen ontdekt u tijdens de uitvoering, type per type.

Het antwoord komt onmiddellijk terug; daarna valt er niets meer op te vragen.

Verzoek

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

Het antwoord lezen

Elke afwijking draagt zowel een machine-identiteit als een leesbare zin. Bouw uw logica op de machine-identiteit: die verandert niet zonder versiewijziging.

severity · code · path · rule: Stabiel contractStabiel. Nieuwe codes kunnen verschijnen; bestaande worden niet hernoemd zonder versiewijziging.
field · message · text: Alleen weergaveVertaald voor weergave. Ze kunnen op elk moment anders geformuleerd worden — vergelijk ze nooit in uw code.
engine.version: Verandert zodra een regelwijziging de score van een ongewijzigd dossier verschuift. Archiveer hem bij uw rapporten.

Het veld “path” volgt de vorm van uw verzoek, zodat u een afwijking rechtstreeks kunt koppelen aan het betrokken veld in uw eigen interface.

header.<veld> · items.<n>.<veld> · documents.<category> · global

Antwoord

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

De velden ontdekken

Aangiftetypes en hun velden zijn openbaar, er is geen sleutel nodig. Dit is de route om een formulier te bouwen, een mapping vanuit uw ERP te voeden of een agent het schema te geven dat hij moet invullen.

De hier teruggegeven namen zijn precies de sleutels voor de kop en voor elke goederenregel. Keuzelijsten komen opgelost en vertaald terug; voeg de parameter toe om ze weg te laten als het antwoord u te zwaar lijkt.

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

Batchverwerking

Tot 25 dossiers per aanroep. Het antwoord is altijd een succes zodra de batch zelf is aanvaard, en elke ingave draagt haar eigen status: één slecht gevormd dossier laat de andere nooit mislukken.

Dekt het resterende quotum niet alle geldige ingaven, dan wordt de hele batch geweigerd in plaats van gedeeltelijk verwerkt — u hoeft nooit te raden waar de verwerking is gestopt.

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

Agenten en hulpmiddelen

Naast de REST-routes zijn dezelfde engine en dezelfde gegevens bereikbaar vanuit een AI-assistent, via een Model Context Protocol-server (MCP), en vanuit een API-client, via een kant-en-klare Postman-collectie. Beide gebruiken de hierboven beschreven API-sleutel en het dagelijkse quotum.

MCP-server

Met de MCP-server kan een assistent douanecodes opzoeken, het EU-invoerrecht van een code lezen, een EORI-, btw- of AEO-nummer controleren in de officiële registers en een conceptaangifte controleren, zonder dat u een regel koppelcode schrijft. Hij antwoordt op POST /api/mcp, met JSON-antwoorden.

Hij is stateless en spreekt beide generaties van het protocol: de revisie 2026-07-28, waarin elk verzoek zijn versie meedraagt, en de eerdere revisies, die beginnen met een initialize-aanroep. Verbinden, ontdekken en de tools opsommen kosten niets; elke toolaanroep verbruikt één eenheid van het dagelijkse quotum van de sleutel.

De authenticatie is hetzelfde bearer-token als de REST-API. Een client die alleen OAuth-aanmelding ondersteunt, zoals de webconnectoren van claude.ai, kan nog niet verbinden: gebruik een client waarmee u een header kunt instellen.

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	Controleer een conceptaangifte: score op 100, niveau en elk probleem met het veld en de actie. Bewaart de inhoud van het bestand niet, tenzij daarom wordt gevraagd.
list_declaration_types	De ondersteunde aangiftesystemen, met autoriteit, regio en verwachte documenten.
describe_declaration_type	De kop- en artikelvelden van een type, om de invoer van check_declaration op te bouwen.
search_hs_codes	Kandidaatcodes uit de Gecombineerde Nomenclatuur op basis van een productomschrijving, in een van de 24 EU-talen.
describe_hs_code	Of een code van 4 tot 10 cijfers bestaat in de geldende nomenclatuur, met het officiële pad en de officiële tekst.
lookup_import_duty	EU-invoerrecht van een code uit de TARIC-gegevens van de Commissie: recht voor derde landen, preferenties voor een oorsprong, contingenten, antidumping en controles.
search_chemical	Een chemische stof op CAS-nummer, CUS-nummer of naam in de ECICS-inventaris van de Commissie: de code van de gecombineerde nomenclatuur die voor elke vermelding wordt gegeven, ter controle.
get_quota_balance	Resterend saldo van een EU-tariefcontingent in de QUOTA-databank van de Commissie, aan de hand van het volgnummer of van een code en een oorsprong: saldo, toestand (open, kritiek, geblokkeerd, uitgeput), periode en tijdstip van de raadpleging.
validate_eori	Formaat van een EORI-nummer en de status ervan in het officiële register (Europese Commissie, HMRC).
validate_vat	Formaat van een EU-btw-nummer en de geldigheid ervan in VIES, met de geregistreerde naam waar die is gepubliceerd.
check_rex	Formaat van een REX-nummer van een geregistreerde exporteur en de status ervan in de REX-databank van de Commissie (geldig, ingetrokken of onbekend), met de data.
screen_sanctions	Een onderneming, persoon of schip tegen de sanctielijsten van de EU, de VN, het Verenigd Koninkrijk en de Verenigde Staten, dagelijks bijgewerkt: elke overeenkomst met haar score, sterk of gedeeltelijk.
search_aeo	Zoek in de database van de Commissie met erkende marktdeelnemers op bedrijfsnaam.

Douanecodes zijn voorstellen op basis van de tekst van de nomenclatuur. Alleen de aangever, of een bindende tariefinlichting van de douane, kan een indeling bevestigen.
Rechten zijn indicatief: voorwaarden, landuitsluitingen en uitgeputte contingenten worden niet beoordeeld. Elk antwoord draagt de referentiedatum van het TARIC-uittreksel, dat maandelijks wordt vernieuwd.
Een register dat niet antwoordt wordt gemeld als niet beschikbaar, nooit als ongeldig nummer. Er wordt nooit iets naar de douane gestuurd.

Postman-collectie

De collectie wordt gegenereerd uit de OpenAPI-specificatie en komt er dus altijd mee overeen: één verzoek per route, gegroepeerd per tag, met een body-skelet voor elke POST. Importeer haar in Postman, vul de variabele apiKey in (bewaard als geheim) en de verzoeken zijn klaar om te verzenden.

De collectie downloaden

Quotum

Elke sleutel krijgt 500 controles per UTC-kalenderdag. De huidige stand reist mee met elk geauthenticeerd antwoord, dus u hebt daar nooit een extra aanroep voor nodig.

Geweigerde aanroepen tellen ook mee: een client die blijft hameren op ongeldige verzoeken remt zichzelf af. Het quotum geldt per sleutel — schrijf ons als u meer nodig hebt.

Antwoord

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

Fouten

Foutmeldingen zijn uitsluitend in het Engels: het zijn protocolberichten, bedoeld voor ontwikkelaars. Alleen de inhoudelijke tekst wordt vertaald.

Elk antwoord draagt een verzoek-id, herhaald in de body. Vermeld die wanneer u ons contacteert — ze brengt ons rechtstreeks bij de aanroep.

{
  "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	Betekenis
400	invalid_json	De body is geen geldige JSON.
422	invalid_request	De JSON is geldig maar de inhoud niet. Het detail noemt het foutieve veld.
401	missing_credentials	Authorization-header ontbreekt of is misvormd.
401	invalid_key	Onbekende sleutel.
401	key_revoked	Ingetrokken sleutel.
403	account_suspended	Het account van de sleutel is geschorst.
415	unsupported_media_type	Het inhoudstype is geen JSON.
413	payload_too_large	Body van het verzoek te groot.
429	rate_limit_exceeded	Dagquotum bereikt. Zie de Retry-After-header.
500	internal_error	Een fout aan onze kant. Probeer opnieuw en meld het met de verzoek-id.

Gegevens en bewaring

Dossiers die via de API binnenkomen zijn gegevens van uw klanten: wij bewaren zo weinig mogelijk, en u hebt een schakelaar om helemaal niets te bewaren.

Stuur “store” als false en er wordt geen dossierinhoud weggeschreven: alleen de score en de afwijkingscodes blijven bewaard.
Anders wordt de dossierinhoud na 30 dagen gewist.
Een sleutel intrekken wist onmiddellijk de inhoud van de dossiers die ermee zijn ingediend.
De verwerking gebeurt in Frankfurt en de databank staat in de Europese Unie.
Er wordt geen bestand geüpload via de API: u verklaart alleen welke documenten u hebt.

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

Wat deze API niet is

De controle helpt bij de voorbereiding. Ze vormt geen validatie door de douaneadministratie, ze dient niets in, en ze vervangt de wettelijke verplichtingen voor uw verrichting niet.

Douanecodes worden gecontroleerd op formaat, op bestaan in de nomenclatuur en, bij invoer in de EU, op de TARIC-maatregelen voor hun oorsprong, nooit op de indeling van de goederen: een bestaande code blijft een code om te verifiëren. De TARIC-maatregelen zijn indicatief (maandelijkse extractie van de Europese Commissie): uitsluitingen van landen, uitgeputte contingenten en voorwaardelijke rechten worden niet beoordeeld.