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 ontsluit de controlemotor van de validator: dertien veldoverstijgende regels, vier regels voor documentvolledigheid en de validators die eigen zijn aan elk aangiftesysteem. Ze verzendt niets en raadpleegt geen tariefdatabank — ze controleert de interne samenhang en het formaat van uw dossier 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.

1Maak een sleutel aan vanuit uw account, onder “API-sleutels”.
2Stuur hem mee in de Authorization-header van elk verzoek.
3Trek 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": 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 }
}

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

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 en op samenhang met de verrichting, nooit tegen een tariefdatabank: een goed gevormde code blijft een code om te verifiëren.