Entwickler

Zollprüfungs-API

Dieselbe Prüfung wie auf dieser Website, aufgerufen aus Ihrer eigenen Software. Sie senden eine Akte als JSON und erhalten einen Score von 100, die blockierenden Punkte, die Hinweise und die empfohlenen Maßnahmen — mit stabilen Fehlercodes und Meldungen in den 24 Amtssprachen der Europäischen Union.

Schlüssel erstellen OpenAPI-Spezifikation

Dies ist eine Server-zu-Server-API. Ein API-Schlüssel ist ein Geheimnis. Aufrufe aus einem Browser werden nicht unterstützt, und auf authentifizierten Routen werden keine CORS-Header gesendet: Ein Schlüssel, der in einen Browser gelangt, ist ein offengelegter Schlüssel.

Überblick

Die API stellt die Prüf-Engine des Validators bereit: vierzehn übergreifende Regeln, fünf TARIC-Regeln, vier Regeln zur Vollständigkeit der Unterlagen und die Validatoren der einzelnen Anmeldesysteme. Sie übermittelt nichts: Sie prüft Format und Stimmigkeit Ihrer Akte, ob die Codes in der Nomenklatur existieren und, bei einer Einfuhr in die EU, die für den Ursprung geltenden TARIC-Maßnahmen (Antidumping, Kontrollen, Präferenzen, Zollsatz), bevor Sie die Anmeldung vorbereiten.

Jede Route ist mit ihrer Version versehen. Die Discovery-Routen und die Spezifikation sind öffentlich: Ein Integrator oder ein Agent kann das Schema lesen, bevor er einen Schlüssel besitzt.

Route	Zweck	Authentifizierung
POST/v1/checks	Prüft eine Akte und gibt den vollständigen Bericht zurück	Schlüssel erforderlich
POST/v1/checks/batch	Prüft bis zu 25 Akten in einem Aufruf	Schlüssel erforderlich
GET/v1/me	Gibt den aktuellen Schlüssel und sein Kontingent zurück, ohne es zu verbrauchen	Schlüssel erforderlich
GET/v1/declaration-types	Listet die erkannten Anmeldearten auf	Öffentlich
GET/v1/declaration-types/{type}	Beschreibt die für eine Art erwarteten Felder	Öffentlich
GET/v1/openapi.json	Die OpenAPI-3.1-Spezifikation dieser API	Öffentlich

Authentifizierung

Die API authentifiziert sich mit einem Bearer-Token. Das Token wird nur einmal angezeigt, bei der Erstellung: Gespeichert wird nur sein Hash, ein verlorener Schlüssel wird ersetzt, nie wiederhergestellt.

Sie können drei aktive Schlüssel gleichzeitig halten. So rotieren Sie einen Schlüssel, ohne Ihre Integration zu unterbrechen: neuen erstellen, ausrollen, alten widerrufen.

01Erstellen Sie einen Schlüssel in Ihrem Konto unter „API-Schlüssel“.
02Senden Sie ihn im Authorization-Header jeder Anfrage.
03Widerrufen Sie ihn bei einem Leck: Die Trennung ist sofort wirksam, und der Inhalt der mit diesem Schlüssel eingereichten Akten wird umgehend gelöscht.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Erste Prüfung

Eine Akte besteht aus einer Art, einem Kopfteil und Warenpositionen. Alle Werte sind Zeichenketten — die Engine übernimmt ihre Auswertung. Die Feldnamen werden zur Laufzeit ermittelt, Art für Art.

Die Antwort kommt sofort zurück; danach ist nichts abzufragen.

Anfrage

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

Die Antwort lesen

Jede Abweichung trägt sowohl eine maschinelle Identität als auch einen lesbaren Satz. Bauen Sie Ihre Logik auf der maschinellen Identität auf: Sie ändert sich nicht ohne Versionswechsel.

severity · code · path · rule: Stabiler VertragStabil. Neue Codes können hinzukommen; bestehende werden ohne Versionswechsel nicht umbenannt.
field · message · text: Nur AnzeigeFür die Anzeige übersetzt. Sie können jederzeit neu formuliert werden — vergleichen Sie sie niemals im Code.
engine.version: Ändert sich, sobald eine Regeländerung den Score einer unveränderten Akte verschiebt. Archivieren Sie sie mit Ihren Berichten.

Das Feld „path“ spiegelt den Aufbau Ihrer Anfrage wider, sodass Sie eine Abweichung direkt dem passenden Feld in Ihrer eigenen Oberfläche zuordnen können.

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

Antwort

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

Felder entdecken

Anmeldearten und ihre Felder sind öffentlich, kein Schlüssel nötig. Das ist die Route, um ein Formular zu bauen, ein Mapping aus Ihrem ERP zu speisen oder einem Agenten das auszufüllende Schema zu geben.

Die hier zurückgegebenen Namen sind genau die Schlüssel für den Kopfteil und für jede Warenposition. Optionslisten kommen aufgelöst und übersetzt zurück; ergänzen Sie den Parameter, um sie wegzulassen, wenn die Antwort zu schwer wirkt.

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

Stapelverarbeitung

Bis zu 25 Akten pro Aufruf. Die Antwort ist immer ein Erfolg, sobald der Stapel selbst angenommen wurde, und jeder Eintrag trägt seinen eigenen Status: Eine fehlerhafte Akte lässt die übrigen nie scheitern.

Deckt das verbleibende Kontingent nicht alle gültigen Einträge ab, wird der gesamte Stapel abgelehnt statt teilweise verarbeitet — Sie müssen nie raten, wo die Verarbeitung abgebrochen ist.

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 und Werkzeuge

Neben den REST-Routen sind dieselbe Engine und dieselben Daten auch von einem KI-Assistenten über einen Model-Context-Protocol-Server (MCP) und von einem API-Client über eine fertige Postman-Collection erreichbar. Beide nutzen den oben beschriebenen API-Schlüssel und das Tageskontingent.

MCP-Server

Der MCP-Server erlaubt einem Assistenten, Zolltarifnummern nachzuschlagen, den EU-Einfuhrzoll einer Nummer zu lesen, eine EORI-, USt-IdNr.- oder AEO-Nummer in den amtlichen Registern zu prüfen und einen Anmeldungsentwurf zu kontrollieren, ohne dass Sie eine Zeile Verbindungscode schreiben. Er antwortet unter POST /api/mcp mit JSON-Antworten.

Er ist zustandslos und spricht beide Generationen des Protokolls: die Revision 2026-07-28, bei der jede Anfrage ihre Version mitführt, und die früheren Revisionen, die mit einem initialize-Aufruf beginnen. Verbindung, Erkennung und das Auflisten der Werkzeuge kosten nichts; jeder Werkzeugaufruf verbraucht eine Einheit des Tageskontingents des Schlüssels.

Die Authentifizierung nutzt dasselbe Bearer-Token wie die REST-API. Ein Client, der nur die OAuth-Anmeldung unterstützt, etwa die Web-Konnektoren von claude.ai, kann sich noch nicht verbinden: Verwenden Sie einen Client, der das Setzen eines Headers erlaubt.

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	Einen Anmeldungsentwurf prüfen: Punktzahl von 100, Stufe und jedes Problem mit Feld und Maßnahme. Speichert den Dateiinhalt nur auf Wunsch.
list_declaration_types	Die unterstützten Anmeldesysteme mit Behörde, Region und erwarteten Unterlagen.
describe_declaration_type	Die Kopf- und Positionsfelder eines Typs, um die Eingabe für check_declaration aufzubauen.
search_hs_codes	Kandidaten der Kombinierten Nomenklatur zu einer Warenbeschreibung, in jeder der 24 EU-Sprachen.
describe_hs_code	Ob ein 4- bis 10-stelliger Code in der geltenden Nomenklatur existiert, mit seinem amtlichen Pfad und Wortlaut.
lookup_import_duty	EU-Einfuhrzoll einer Nummer aus den TARIC-Daten der Kommission: Drittlandszoll, Präferenzen für einen Ursprung, Kontingente, Antidumping und Kontrollen.
search_chemical	Ein chemischer Stoff nach CAS-Nummer, CUS-Nummer oder Name im ECICS-Verzeichnis der Kommission: der zu jedem Eintrag angegebene Code der Kombinierten Nomenklatur, zur Prüfung.
get_quota_balance	Verbleibendes Saldo eines EU-Zollkontingents in der QUOTA-Datenbank der Kommission, anhand seiner Ordnungsnummer oder eines Codes und eines Ursprungs: Saldo, Zustand (offen, kritisch, gesperrt, ausgeschöpft), Zeitraum und Zeitpunkt der Abfrage.
validate_eori	Format einer EORI-Nummer und ihr Status im amtlichen Register (Europäische Kommission, HMRC).
validate_vat	Format einer EU-Umsatzsteuer-Identifikationsnummer und ihre Gültigkeit im VIES, mit dem eingetragenen Namen, sofern veröffentlicht.
check_rex	Format einer REX-Nummer (registrierter Ausführer) und ihr Status in der REX-Datenbank der Kommission (gültig, widerrufen oder unbekannt), mit ihren Daten.
screen_sanctions	Ein Unternehmen, eine Person oder ein Schiff gegen die Sanktionslisten der EU, der UN, des Vereinigten Königreichs und der USA, täglich aktualisiert: jeder Treffer mit seinem Score, stark oder teilweise.
search_aeo	Suche in der Datenbank der Kommission zu zugelassenen Wirtschaftsbeteiligten nach Firmenname.

Zolltarifnummern sind Vorschläge aus dem Wortlaut der Nomenklatur. Nur der Anmelder oder eine Verbindliche Zolltarifauskunft des Zolls kann eine Einreihung bestätigen.
Zölle sind Richtwerte: Bedingungen, Länderausschlüsse und erschöpfte Kontingente werden nicht ausgewertet. Jede Antwort trägt das Stichtagsdatum des TARIC-Auszugs, der monatlich aktualisiert wird.
Ein Register, das nicht antwortet, wird als nicht verfügbar gemeldet, nie als ungültige Nummer. Es wird nie etwas an den Zoll gesendet.

Postman-Collection

Die Collection wird aus der OpenAPI-Spezifikation erzeugt und stimmt daher immer mit ihr überein: eine Anfrage pro Route, nach Tag gruppiert, mit einem Body-Gerüst für jeden POST. Importieren Sie sie in Postman, füllen Sie die Variable apiKey (als Geheimnis gespeichert), und die Anfragen sind versandfertig.

Collection herunterladen

Kontingent

Jeder Schlüssel erhält 500 Prüfungen pro UTC-Kalendertag. Der aktuelle Stand reist mit jeder authentifizierten Antwort mit, ein zusätzlicher Aufruf ist dafür nie nötig.

Abgelehnte Aufrufe zählen ebenfalls: Ein Client, der auf ungültigen Anfragen schleift, bremst sich selbst. Das Kontingent gilt je Schlüssel — schreiben Sie uns, wenn Sie mehr benötigen.

Antwort

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

Fehler

Fehlermeldungen sind ausschließlich englisch: Es sind Protokollmeldungen für Entwickler. Nur der fachliche Inhalt wird übersetzt.

Jede Antwort trägt eine Request-ID, die im Rumpf wiederholt wird. Nennen Sie sie bei einer Anfrage an uns — sie führt uns direkt zum Aufruf.

{
  "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	Bedeutung
400	invalid_json	Der Rumpf ist kein gültiges JSON.
422	invalid_request	Das JSON ist gültig, sein Inhalt nicht. Die Details nennen das fehlerhafte Feld.
401	missing_credentials	Authorization-Header fehlt oder ist fehlerhaft.
401	invalid_key	Unbekannter Schlüssel.
401	key_revoked	Widerrufener Schlüssel.
403	account_suspended	Das Konto des Schlüssels ist gesperrt.
415	unsupported_media_type	Der Inhaltstyp ist kein JSON.
413	payload_too_large	Anfragerumpf zu groß.
429	rate_limit_exceeded	Tageskontingent erreicht. Siehe Retry-After-Header.
500	internal_error	Ein Fehler auf unserer Seite. Erneut versuchen und uns mit der Request-ID melden.

Daten und Aufbewahrung

Über die API gesendete Akten sind Daten Ihrer Kunden: Wir behalten so wenig wie möglich, und Sie haben einen Schalter, um gar nichts zu behalten.

Senden Sie „store“ als false, dann wird kein Akteninhalt geschrieben: Nur Score und Fehlercodes bleiben erhalten.
Andernfalls wird der Akteninhalt nach 30 Tagen gelöscht.
Das Widerrufen eines Schlüssels löscht sofort den Inhalt der damit eingereichten Akten.
Die Verarbeitung erfolgt in Frankfurt, die Datenbank liegt in der Europäischen Union.
Über die API wird keine Datei hochgeladen: Sie erklären lediglich, welche Unterlagen Sie besitzen.

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

Was diese API nicht ist

Die Prüfung hilft bei der Vorbereitung. Sie ist keine Validierung durch die Zollverwaltung, sie übermittelt nichts, und sie ersetzt nicht die für Ihren Vorgang geltenden rechtlichen Pflichten.

Zollcodes werden auf Format, auf Existenz in der Nomenklatur und, bei Einfuhren in die EU, auf die TARIC-Maßnahmen ihres Ursprungs geprüft, nie auf die Einreihung der Ware: Ein existierender Code bleibt ein zu prüfender Code. Die TARIC-Maßnahmen sind unverbindlich (monatlicher Auszug der Europäischen Kommission): Länderausschlüsse, ausgeschöpfte Kontingente und bedingte Zölle werden nicht bewertet.