Jak działa nasz kalkulator wyłączeń i wyszukiwarka numerów UN? Od PDF do API

Branża TSL (Transport, Spedycja, Logistyka) od lat opiera się na opasłych tomach umowy ADR. W erze cyfryzacji manualne przeszukiwanie tabel czy korzystanie z plików PDF jest nieefektywne i podatne na błędy ludzkie.

W tym wpisie technologicznym odsłaniamy kulisy powstania ADR Tool (do którego dostęp możliwy jest przez app.kocie.mba) - aplikacji PWA (Progressive Web App), która przekształca statyczne wpisy w Tabeli 3.2 A Umowy ADR w dynamiczny silnik obliczeniowy dostępny przez API.

Od PDF do ustrukturyzowanej bazy danych

Projekt ten nie powstał w wyniku prostego "kopiuj-wklej". Źródłem danych jest oficjalna dokumentacja UNECE (United Nations Economic Commission for Europe) oraz tłumaczenie Umowy ADR na język polski, opublikowane w Dzienniku Ustaw. Proces cyfryzacji danych przeszedł długą ewolucję:

1. Ekstrakcja danych - pierwszym krokiem było parsowanie oficjalnych plików PDF zawierających Tabele A i B umowy ADR;
2. Normalizacja - surowe dane zostały przeniesione do arkuszy kalkulacyjnych (Excel), gdzie nastąpiło ich czyszczenie, typowanie danych i weryfikacja pod kątem błędów OCR;
3. JSON Transformation - statecznie dane zostały skonwertowane do lekkiego formatu JSON. Dzięki temu aplikacja nie musi ładować ciężkich bibliotek SQL - operuje na zoptymalizowanej strukturze danych, co zapewnia milisekundowe czasy odpowiedzi.

Wyszukiwarka ADR i wyszukiwarka numerów UN

Serce aplikacji stanowi silnik wyszukiwania działający w czasie rzeczywistym. W przeciwieństwie do tradycyjnych rozwiązań, zaimplementowaliśmy tutaj logikę "fuzzy search" (wyszukiwania rozmytego). Użytkownik nie musi znać dokładnego brzmienia nazwy chemicznej. Wpisanie fragmentu nazwy (np. "benzyna") lub numeru UN (np. "1202") natychmiast powoduje wysłanie zapytania do API w celu przeszukiwania bazy.

Kalkulator wyłączeń

Największym wyzwaniem inżynieryjnym nie było samo wyświetlanie danych, ale implementacja logiki biznesowej ADR. Kalkulator działa w modelu dwuetapowym:

1. Agregacja - użytkownik najpierw wyszukuje towary (korzystając z modułu search) i dodaje je do wirtualnego "ładunku" (manifestu). Aplikacja przechowuje stan sesji (state management) w pamięci lokalnej urządzenia;
2. Przetwarzanie: Dla każdej pozycji pobierana jest kategoria transportowa. Na jej podstawie system dobiera odpowiedni mnożnik (np. x0, x1, x3, x50) zgodnie z przepisami.

Wyłączenie 1.1.3.6

Kluczową funkcjonalnością dla przewoźników drobnicowych jest weryfikacja wyłączenia na podstawie przepisu 1.1.3.6 (tzw. "małe ADR"). Algorytm sumuje punkty dla całego ładunku według wzoru:

Σ (Ilość towaru * Mnożnik kategorii) = Liczba punktów

System automatycznie waliduje wynik względem progu krytycznego (1000 punktów).

• Wynik < 1000 pkt - aplikacja zwraca status ZIELONY (możliwy przewóz na wyłączeniu, brak konieczności posiadania pełnych uprawnień ADR przez kierowcę, brak tablic pomarańczowych);
• Wynik > 1000 pkt - aplikacja zwraca status CZERWONY (pełny ADR wymagany).

Dokumentacja API i integracje

ADR Tool to nie tylko interfejs graficzny dla kierowcy. To w pełni funkcjonalne REST API, które udostępniamy dla zewnętrznych systemów.

Architektura API opiera się na prostych zapytaniach GET, zwracających odpowiedzi w formacie JSON:

• Pobranie szczegółów konkretnego towaru:

  GET https://app.kocie.mba/api/?un=1202

  Zwraca pełny obiekt z nazwą, klasą, kodem tunelu i kategoriami pakowania dla oleju napędowego.

• Wyszukiwanie (Query):

  GET https://app.kocie.mba/api/?q=kwas

  Zwraca tablicę obiektów pasujących do zapytania tekstowego.

Rate Limiting i Tokeny VIP

W celu ochrony infrastruktury przed atakami DDoS, publiczne API posiada limity zapytań na adres IP.

Dla partnerów biznesowych oferujemy specjalistyczne tokeny. Przekazanie parametru &token=YOUR_KEY w zapytaniu URL zdejmuje limity, pozwalając na masowe przetwarzanie danych w czasie rzeczywistym.

Możliwości integracji (B2B)

Dzięki otwartej architekturze API, moduł ADR Tool może zostać zintegrowany bezpośrednio z Twoim ekosystemem IT:

• Systemy CRM/ERP - automatyczne uzupełnianie danych o towarze niebezpiecznym na fakturach i zleceniach;
• Systemy TMS (Transport Management Systems) - weryfikacja ładunków na etapie planowania trasy;
• Aplikacje magazynowe (WMS) - szybka weryfikacja etykiet i wymogów pakowania.

Zainteresowany dostępem do API lub dedykowaną integracją? Skontaktuj się z nami!