Dokumentacja API Ver. 1.0.d.5

Wprowadzenie

To API umożliwia zewnętrznym aplikacjom sprawdzanie statusu przesyłek w naszym systemie. Dostęp do statusu jest możliwy poprzez numer przesyłki.

API jest publiczne i nie wymaga autoryzacji. Prosimy o odpowiedzialne korzystanie i unikanie nadmiernej liczby zapytań. Wprowadzono podstawowe mechanizmy ochrony przed nadużyciami (tzw. throttling), a wszystkie próby użycia kodu są 👀 rejestrowane.

Endpoint: Pobieranie statusu przesyłki

Pobiera aktualny status i historię zdarzeń dla danej przesyłki.

URL -> https://api.przesylkamiejska.pl/v1/

Endpoint przyjmuje przyjazne adresy URL w następujących formatach:

GET /sledzenie/{PelnyNumerPrzesylki}

GET /sledzenie/{PelnyNumerPrzesylki}/{SkroconeMiasto}

Lub klasyczne adresy endpoint w następujących formatach:

GET /api/tracking-status/{PelnyNumerPrzesylki}

GET /api/tracking-status/{PelnyNumerPrzesylki}/{SkroconeMiasto}

Parametry URL (Path Parameters)

• {PelnyNumerPrzesylki} (wymagany, string): Unikalny numer śledzenia przesyłki.
• {SkroconeMiasto} (opcjonalny, string): Nazwa regionu, z którym powiązane jest miasto (np. 3city, btom).
  • Jeśli {SkroconeMiasto} zostanie podane, API będzie próbować wyszukać przesyłkę tylko w przypisanym do tego mieście.
  • Jeśli {SkroconeMiasto} zostanie pominięte, API najpierw spróbuje wyszukać przesyłkę w mieści 3city. Jeśli tam jej nie znajdzie, spróbuje wyszukać w mieście btom.

Mechanizm Throttlingu (Ochrona przed nadużyciami)

W celu ochrony przed nadmiernym obciążeniem serwera i atakami brute-force, API implementuje mechanizm ograniczania liczby zapytań (throttling):

• Minimalny interwał: Z każdego adresu IP, kolejne zapytanie może być wysłane z minimalnym opóźnieniem (domyślnie 5 sekundy).
   Krótsze odstępy skutkują automatycznym opóźnieniem odpowiedzi.
• Maksymalna liczba zapytań: Istnieje również limit zapytań z jednego adresu IP w danym okresie (domyślnie 20 zapytań na minutę).
   Po przekroczeniu tego limitu, API zwróci błąd 429 Too Many Requests.

Przykładowe żądania (cURL)

curl -X GET "https://api.przesylkamiejska.pl/v1/api/tracking-status/1234567890"

PrettyURL: curl -X GET "https://api.przesylkamiejska.pl/v1/api/sledzenie/1234567890"

curl -X GET "https://api.przesylkamiejska.pl/v1/api/tracking-status/1234567890/3city"

PrettyURL: curl -X GET "https://api.przesylkamiejska.pl/v1/api/sledzenie/1234567890/3city"

Przykładowe żądanie (JavaScript - Fetch API)

// Zapytanie bez określania miasta (backend spróbuje domyślnej kolejności)
fetch('https://api.przesylkamiejska.pl/v1/api/tracking-status/1234567890')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

// Zapytanie z określeniem miasta
fetch('https://api.przesylkamiejska.pl/v1/api/tracking-status/ABC9876543/btom')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
                            

PrettyURL:
                    
// Zapytanie bez określania miasta (backend spróbuje domyślnej kolejności)
fetch('https://api.przesylkamiejska.pl/v1/api/sledzenie/1234567890')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

// Zapytanie z określeniem miasta
fetch('https://api.przesylkamiejska.pl/v1/api/sledzenie/ABC9876543/btom')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
                            
                    

Przykładowa odpowiedź sukcesu (JSON)

{
    "status": "success",
    "tracking_number": "1234567890",
    "notes": [
        {
            "date": "7 października 2024 o 14:15",
            "event": "Zlecenie zostało złożone przez nadawcę"
        },
        {
            "date": "7 października 2024 o 15:30",
            "event": "Przesyłka została odebrana przez kuriera."
        },
        {
            "date": "8 października 2024 o 09:00",
            "event": "Przesyłka przekazana kurierem zewnętrznym (InPost) o numerze śledzenia: ABC123456789 (Śledź)."
        },
        {
            "date": "8 października 2024 o 14:00",
            "event": "Przesyłka została dostarczona do odbiorcy."
        }
    ]
}
                            

Pola odpowiedzi sukcesu

• status (string): Zawsze 'success' w przypadku powodzenia.
• tracking_number (string): Numer przesyłki, który został zapytany.
• notes (array of objects): Tablica obiektów, gdzie każdy obiekt reprezentuje zdarzenie w historii przesyłki.
  • date (string): Data i czas zdarzenia w formacie "Dzień NazwaMiesiąca Rok o GG:MM".
  • event (string): Opis zdarzenia. Może zawierać tagi HTML (np. <a>, <span>) dla dodatkowych informacji (np. linki do śledzenia zewnętrznych przewoźników).

Przykładowa odpowiedź błędu (JSON)

{
    "status": "error",
    "message": "Nie znaleziono przesyłki o podanym numerze."
}
                            

Pola odpowiedzi błędu

• status (string): Zawsze 'error' w przypadku błędu.
• message (string): Krótki opis błędu.

Kody statusu HTTP

• 200 OK: Żądanie zostało przetworzone pomyślnie.
• 400 Bad Request: Brak numeru śledzenia lub nieprawidłowy format żądania.
• 404 Not Found: Przesyłka o podanym numerze nie została znaleziona.
• 405 Method Not Allowed: Użyto nieprawidłowej metody HTTP (np. POST zamiast GET).
• 429 Too Many Requests: Przekroczono limit liczby zapytań (throttling).
• 500 Internal Server Error: Wystąpił błąd po stronie serwera.