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: dreizehn feldübergreifende Regeln, vier Regeln zur Vollständigkeit der Unterlagen und die für jedes Anmeldesystem spezifischen Validatoren. Sie übermittelt nichts und fragt keine Zolltarifdatenbank ab — sie prüft die interne Stimmigkeit und das Format Ihrer Akte, 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.

1Erstellen Sie einen Schlüssel in Ihrem Konto unter „API-Schlüssel“.
2Senden Sie ihn im Authorization-Header jeder Anfrage.
3Widerrufen 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": 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 }
}

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

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 und Stimmigkeit mit dem Vorgang geprüft, nie gegen eine Zolltarifdatenbank: Ein wohlgeformter Code bleibt ein zu prüfender Code.