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: trzynaście reguł przekrojowych, cztery reguły kompletności dokumentów oraz walidatory właściwe dla każdego systemu zgłoszeniowego. Niczego nie przesyła i nie odpytuje żadnej bazy taryfowej — sprawdza wewnętrzną spójność i format Twojej dokumentacji, 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.

1Utwórz klucz na swoim koncie, w sekcji „Klucze API”.
2Wysyłaj go w nagłówku Authorization każdego żądania.
3Unieważ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": 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 }
}

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

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 sprawdzane są pod kątem formatu i spójności z operacją, nigdy wobec bazy taryfowej: poprawnie zbudowany kod pozostaje kodem do zweryfikowania.