Dla programistów

API kontroli celnej

Ta sama kontrola co na tej stronie, wywoływana z Twojego oprogramowania. Wysyłasz dokumentację w JSON i otrzymujesz wynik na 100, punkty blokujące, ostrzeżenia oraz zalecane działania — ze stabilnymi kodami nieprawidłowości i komunikatami w 24 językach urzędowych Unii Europejskiej.

Utwórz klucz Specyfikacja OpenAPI

To API działa między serwerami. Klucz API jest tajemnicą. Wywołania z przeglądarki nie są obsługiwane, a na trasach uwierzytelnionych nie są wysyłane nagłówki CORS: klucz, który trafia do przeglądarki, jest kluczem ujawnionym.

Przegląd

API udostępnia silnik kontroli walidatora: czternaście reguł przekrojowych, pięć reguł TARIC, cztery reguły kompletności dokumentów i walidatory właściwe dla każdego systemu zgłoszeń. Niczego nie wysyła: sprawdza format i spójność dokumentacji, istnienie kodów w nomenklaturze oraz, przy przywozie do UE, środki TARIC obowiązujące dla pochodzenia (antydumping, kontrole, preferencje, stawka cła), zanim przygotujesz zgłoszenie.

Każda trasa ma prefiks wersji. Trasy odkrywania i specyfikacja są publiczne: integrator albo agent może odczytać schemat, zanim jeszcze będzie miał klucz.

Trasa	Rola	Uwierzytelnianie
POST/v1/checks	Sprawdza dokumentację i zwraca pełny raport	Wymagany klucz
POST/v1/checks/batch	Sprawdza do 25 dokumentacji w jednym wywołaniu	Wymagany klucz
GET/v1/me	Zwraca bieżący klucz i jego limit, nie zużywając go	Wymagany klucz
GET/v1/declaration-types	Wypisuje rozpoznawane typy zgłoszeń	Publiczna
GET/v1/declaration-types/{type}	Opisuje pola oczekiwane dla danego typu	Publiczna
GET/v1/openapi.json	Specyfikacja OpenAPI 3.1 tego API	Publiczna

Uwierzytelnianie

API uwierzytelnia się tokenem bearer. Token pokazywany jest tylko raz, przy tworzeniu: przechowywany jest wyłącznie jego skrót, więc zgubiony klucz się wymienia, nigdy nie odzyskuje.

Możesz mieć jednocześnie trzy aktywne klucze, co pozwala rotować klucz bez przerywania integracji: utwórz nowy, wdróż go, a potem unieważnij stary.

01Utwórz klucz na swoim koncie, w sekcji „Klucze API”.
02Wysyłaj go w nagłówku Authorization każdego żądania.
03Unieważnij go w razie wycieku: odcięcie jest natychmiastowe, a treść dokumentacji przesłanej tym kluczem zostaje od razu usunięta.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pierwsza kontrola

Dokumentacja składa się z typu, nagłówka i pozycji towarowych. Wszystkie wartości są ciągami znaków: silnik sam je interpretuje. Nazwy pól odkrywa się w czasie działania, typ po typie.

Odpowiedź przychodzi natychmiast; później nie ma czego odpytywać.

Żądanie

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

Czytanie odpowiedzi

Każda nieprawidłowość niesie zarówno tożsamość maszynową, jak i czytelne zdanie. Buduj swoją logikę na tożsamości maszynowej: nie zmienia się bez zmiany wersji.

severity · code · path · rule: Stabilny kontraktStabilne. Mogą pojawić się nowe kody; istniejące nie są zmieniane bez zmiany wersji.
field · message · text: Tylko wyświetlaniePrzetłumaczone do wyświetlania. Mogą zostać przeredagowane w każdej chwili — nigdy nie porównuj ich w kodzie.
engine.version: Zmienia się, gdy zmiana reguł przesuwa wynik niezmienionej dokumentacji. Archiwizuj ją razem z raportami.

Pole „path” odzwierciedla kształt Twojego żądania, więc możesz powiązać nieprawidłowość wprost z odpowiednim polem we własnym interfejsie.

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

Odpowiedź

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

Odkrywanie pól

Typy zgłoszeń i ich pola są publiczne, klucz nie jest potrzebny. To trasa do zbudowania formularza, zasilenia mapowania z Twojego ERP albo przekazania agentowi schematu, który ma wypełnić.

Zwracane tutaj nazwy to dokładnie klucze używane w nagłówku i w każdej pozycji towarowej. Listy opcji wracają rozwiązane i przetłumaczone; dodaj parametr, aby je pominąć, jeśli odpowiedź wydaje się zbyt ciężka.

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

Przetwarzanie wsadowe

Do 25 dokumentacji na wywołanie. Odpowiedź jest zawsze sukcesem, gdy paczka zostanie przyjęta, a każdy wpis niesie własny status: jedna źle sformowana dokumentacja nigdy nie unieważnia pozostałych.

Jeśli pozostały limit nie pokrywa wszystkich poprawnych wpisów, cała paczka zostaje odrzucona zamiast przetworzona częściowo — nigdy nie musisz zgadywać, gdzie przetwarzanie się zatrzymało.

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

Agenci i narzędzia

Oprócz tras REST ten sam silnik i te same dane są dostępne z asystenta AI, przez serwer Model Context Protocol (MCP), oraz z klienta API, przez gotową kolekcję Postmana. Oba korzystają z klucza API i dziennego limitu opisanych wyżej.

Serwer MCP

Serwer MCP pozwala asystentowi wyszukiwać kody celne, odczytywać unijne cło przywozowe dla kodu, sprawdzać numer EORI, VAT lub AEO w oficjalnych rejestrach i weryfikować projekt zgłoszenia, bez pisania ani jednej linii kodu łączącego. Odpowiada pod adresem POST /api/mcp, odpowiedziami JSON.

Jest bezstanowy i obsługuje obie generacje protokołu: rewizję 2026-07-28, w której każde żądanie niesie swoją wersję, oraz wcześniejsze rewizje, które zaczynają się wywołaniem initialize. Połączenie, wykrywanie i wypis narzędzi nic nie kosztują; każde wywołanie narzędzia zużywa jedną jednostkę dziennego limitu klucza.

Uwierzytelnianie odbywa się tym samym tokenem bearer co w API REST. Klient obsługujący wyłącznie logowanie OAuth, taki jak konektory webowe claude.ai, nie może się jeszcze połączyć: użyj klienta, który pozwala ustawić nagłówek.

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	Sprawdza projekt zgłoszenia: wynik na 100, poziom i każdy problem z polem i działaniem. Nie przechowuje zawartości pliku, chyba że o to poproszono.
list_declaration_types	Obsługiwane systemy zgłoszeń, z organem, regionem i oczekiwanymi dokumentami.
describe_declaration_type	Pola nagłówka i pozycji danego typu, aby zbudować dane wejściowe dla check_declaration.
search_hs_codes	Kody kandydujące z Nomenklatury scalonej na podstawie opisu produktu, w dowolnym z 24 języków UE.
describe_hs_code	Czy kod 4–10-cyfrowy istnieje w obowiązującej nomenklaturze, z jego oficjalną ścieżką i brzmieniem.
lookup_import_duty	Unijne cło przywozowe dla kodu na podstawie danych TARIC Komisji: cło dla państw trzecich, preferencje dla pochodzenia, kontyngenty, antydumping i kontrole.
search_chemical	Substancja chemiczna według numeru CAS, numeru CUS lub nazwy w wykazie ECICS Komisji: kod Nomenklatury Scalonej podany dla każdej pozycji, do weryfikacji.
get_quota_balance	Pozostałe saldo kontyngentu taryfowego UE w bazie QUOTA Komisji, według numeru porządkowego albo kodu i pochodzenia: saldo, stan (otwarty, krytyczny, zablokowany, wyczerpany), okres i godzina odczytu.
validate_eori	Format numeru EORI i jego status w oficjalnym rejestrze (Komisja Europejska, HMRC).
validate_vat	Format unijnego numeru VAT i jego ważność w VIES, wraz z zarejestrowaną nazwą, jeśli jest opublikowana.
check_rex	Format numeru REX zarejestrowanego eksportera i jego status w bazie REX Komisji (ważny, unieważniony lub nieznany), z datami.
screen_sanctions	Firma, osoba lub statek na listach sankcyjnych UE, ONZ, Zjednoczonego Królestwa i Stanów Zjednoczonych, aktualizowanych codziennie: każde dopasowanie z wynikiem, silne lub częściowe.
search_aeo	Wyszukiwanie w bazie Komisji upoważnionych przedsiębiorców gospodarczych po nazwie firmy.

Kody celne to propozycje oparte na brzmieniu nomenklatury. Klasyfikację może potwierdzić tylko zgłaszający lub wiążąca informacja taryfowa organu celnego.
Cła mają charakter orientacyjny: warunki, wyłączenia krajowe i wyczerpane kontyngenty nie są oceniane. Każda odpowiedź niesie datę odniesienia wyciągu z TARIC, odświeżanego co miesiąc.
Rejestr, który nie odpowiada, jest zgłaszany jako niedostępny, nigdy jako nieprawidłowy numer. Do organu celnego nigdy nic nie jest wysyłane.

Kolekcja Postmana

Kolekcja jest generowana ze specyfikacji OpenAPI, więc zawsze jej odpowiada: jedno żądanie na trasę, pogrupowane według tagu, z szablonem treści dla każdego POST. Zaimportuj ją do Postmana, uzupełnij zmienną apiKey (przechowywaną jako sekret) i żądania są gotowe do wysłania.

Pobierz kolekcję

Limit

Każdy klucz ma 500 kontroli na dobę kalendarzową UTC. Bieżący stan podróżuje z każdą uwierzytelnioną odpowiedzią, więc nigdy nie potrzebujesz dodatkowego wywołania, by go poznać.

Odrzucone wywołania też się liczą: klient zapętlony na nieprawidłowych żądaniach sam się ogranicza. Limit jest ustalany na klucz — napisz do nas, jeśli potrzebujesz więcej.

Odpowiedź

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

Błędy

Komunikaty błędów są wyłącznie po angielsku: to komunikaty protokołu, przeznaczone dla programistów. Tłumaczona jest tylko treść merytoryczna.

Każda odpowiedź niesie identyfikator żądania, powtórzony w treści. Podaj go, kontaktując się z nami — prowadzi nas prosto do wywołania.

{
  "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	Znaczenie
400	invalid_json	Treść nie jest poprawnym JSON-em.
422	invalid_request	JSON jest poprawny, ale jego treść nie. Szczegóły wskazują błędne pole.
401	missing_credentials	Brak nagłówka Authorization lub jest źle sformowany.
401	invalid_key	Nieznany klucz.
401	key_revoked	Klucz unieważniony.
403	account_suspended	Konto właściciela klucza jest zawieszone.
415	unsupported_media_type	Typ treści nie jest JSON-em.
413	payload_too_large	Treść żądania jest zbyt duża.
429	rate_limit_exceeded	Osiągnięto limit dzienny. Zobacz nagłówek Retry-After.
500	internal_error	Błąd po naszej stronie. Spróbuj ponownie, a potem zgłoś go z identyfikatorem żądania.

Dane i przechowywanie

Dokumentacja przesłana przez API to dane Twoich klientów: przechowujemy jak najmniej, a Ty masz przełącznik, by nie przechowywać niczego.

Wyślij „store” jako false, a żadna treść dokumentacji nie zostanie zapisana: pozostaną tylko wynik i kody nieprawidłowości.
W przeciwnym razie treść dokumentacji jest usuwana po 30 dniach.
Unieważnienie klucza natychmiast usuwa treść dokumentacji przesłanej tym kluczem.
Przetwarzanie odbywa się we Frankfurcie, a baza danych jest w Unii Europejskiej.
Przez API nie przesyła się żadnych plików: deklarujesz jedynie, które dokumenty posiadasz.

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

Czym to API nie jest

Kontrola pomaga w przygotowaniu. Nie stanowi zatwierdzenia przez administrację celną, niczego nie składa i nie zastępuje obowiązków regulacyjnych dotyczących Twojej operacji.

Kody celne są sprawdzane pod kątem formatu, istnienia w nomenklaturze oraz, przy przywozie do UE, środków TARIC dla ich pochodzenia, nigdy pod kątem klasyfikacji towaru: istniejący kod pozostaje kodem do weryfikacji. Środki TARIC mają charakter orientacyjny (comiesięczny wyciąg Komisji Europejskiej): wyłączenia krajów, wyczerpane kontyngenty i cła warunkowe nie są oceniane.