Dokumentacja API Ver. 1.0.d.5

Wprowadzenie

To API umożliwia zewnętrznym aplikacjom przesłanie danych przesyłki i uzyskanie wyceny zgodnie z aktualnym cennikiem i zasadami.

API jest publiczne i nie wymaga autoryzacji, ale wymaga wysłania danych w formacie JSON metodą POST. Prosimy o odpowiedzialne korzystanie i unikanie nadmiernej liczby zapytań. Nie stosujemy throttlingu, natomiast wszystkie próby użycia API są 👀 rejestrowane.

Endpoint: Obliczanie wyceny przesyłki

Na podstawie przesłanych danych wylicza cenę przesyłki oraz zwraca szczegółowy breakdown ceny.

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

Endpoint:

POST /pricing/calculate

Metody HTTP

• POST /pricing/calculate: Właściwa metoda wyceny, która przyjmuje dane JSON i zwraca wycenę.
• OPTIONS /pricing/calculate: Obsługa zapytania OPTIONS (CORS Preflight), zwraca odpowiednie nagłówki i status 204 (No Content). Więcej szczegółów na końcu.

Dane wejściowe (JSON)

Poniżej opisujemy pola, które należy przesłać w treści zapytania.

A. Dane Podstawowe (minimum wymagane)

• origin_city (string): Miasto nadania, np. "Gdańsk".
• origin_district (string): Dzielnica nadania, np. "Wrzeszcz".
• destination_city (string): Miasto docelowe, np. "Gdynia".
• destination_district (string): Dzielnica docelowa, np. "Orłowo".
• weight_kg (float): Waga przesyłki w kilogramach, np. 5.5.
• value (float): Zadeklarowana wartość przesyłki w złotówkach (do ubezpieczenia), np. 250.00.
• dimensions (array): Tablica trzech wymiarów paczki w cm, np. [40, 30, 20].

B. Dane Opcjonalne (wybierane przez klienta)

• return_docs (bool): true, jeśli klient chce usługę zwrotu podpisanych dokumentów.
• wait_time_min (int): To pole nie jest dla klienta. Jest ono używane przez system po wykonaniu usługi. Kurier w swoim panelu wpisuje, że czekał np. 10 minut, a ta wartość jest dodawana do zlecenia przed ostatecznym rozliczeniem.
• no_show (bool): Flaga oznaczająca pusty podjazd (zwykle ustalana przez kuriera/admina).

C. Dane Specjalne (logika biznesowa, admin)

• individual_quote (bool): Ustaw na true, jeśli wycena ma być ręczna (np. nietypowy transport).
• agreed_price (float): Ustaw na true, jeśli cena uzgodniona została ręcznie z klientem (pomija automatyczne wyliczenia bazowe).
• discount (float): Kwota rabatu przyznanego ręcznie przez admina (odejmowana na końcu).
• is_document (bool): Flaga oznaczająca przesyłkę dokumentową, używana do specjalnych zasad.

Przykładowe żądania (cURL)

curl -X POST "https://api.przesylkamiejska.pl/v1/pricing/calculate" \
-H "Content-Type: application/json" \
-d '{
  "origin_city": "Gdańsk",
  "origin_district": "Wrzeszcz",
  "destination_city": "Gdynia",
  "destination_district": "Orłowo",
  "weight_kg": 5.5,
  "value": 250.00,
  "dimensions": [40, 30, 20],
  "return_docs": true
}'

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

// Obliczenie wyceny przesyłki metodą POST z JSON
fetch('https://api.przesylkamiejska.pl/v1/pricing/calculate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        origin_city: "Gdańsk",
        origin_district: "Wrzeszcz",
        destination_city: "Gdynia",
        destination_district: "Orłowo",
        weight_kg: 5.5,
        value: 250.00,
        dimensions: [40, 30, 20],
        return_docs: true
    })
})
.then(response => response.json())
.then(data => console.log(data)) // wynik w konsoli
.catch(error => console.error('Error:', error));
    

Opis działania

Metoda przetwarza dane wejściowe i zwraca wycenę uwzględniającą:

• Cenę bazową w zależności od strefy (lokalna, między miastami itp.).
• Opłaty dodatkowe, np. zwrot dokumentów, czas oczekiwania.
• Rabaty i ewentualne ceny uzgodnione ręcznie.
• Podatek VAT naliczany zgodnie z aktualnymi stawkami.
• Ostrzeżenia, które nie blokują wyceny, ale mogą wymagać uwagi klienta.

Przykładowa odpowiedź sukcesu (JSON)

{
  "success": true,
  "error": null,
  "quote": {
    "base_price": 15.00,
    "price_type": "intercity",
    "surcharges": {
      "return_docs": 5.00
    },
    "discount": 0.00,
    "total_price_net": 20.00,
    "vat_amount": 4.60,
    "total_price_gross": 24.60,
    "warnings": []
  }
}

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

{
  "success": false,
  "error": "Przesyłka przekracza maksymalną dopuszczalną wagę 30 kg.",
  "quote": null
}

Szczegóły pól w odpowiedzi

• success (bool): true, jeśli wycena powiodła się.
• error (string|null): Komunikat błędu jeśli success jest false.
• quote (object|null): Szczegóły wyceny jeśli success jest true.

• base_price (float): Cena bazowa netto.
• price_type (string): Typ ceny bazowej, może przyjmować wartości:
  • local – w obrębie jednego miasta,
  • intercity – pomiędzy miastami,
  • forwarding – przesyłka przekazana zewnętrznemu przewoźnikowi (stała cena),
  • agreed – cena ustalona ręcznie,
  • individual – wycena indywidualna, do podania później.
• surcharges (object): Opłaty dodatkowe, np. {"return_docs": 5.00}.
• discount (float): Kwota rabatu.
• total_price_net (float): Łączna cena netto (bazowa + opłaty – rabat).
• vat_amount (float): Kwota podatku VAT.
• total_price_gross (float): Cena brutto do zapłaty przez klienta.
• warnings (array): Tablica ostrzeżeń (np. konieczność ubezpieczenia). Mogą być puste.

Uwagi

• Waga przesyłki nie może przekraczać limitów ustawionych w konfiguracji cennika.
• Opcje takie jak wait_time_min i no_show są przeznaczone do użycia wewnętrznego (np. przez kurierów, adminów) i zwykle nie są wysyłane przez klienta.
• W przypadku zleceń wymagających indywidualnej wyceny należy ustawić flagę individual_quote na true.

Obsługa zapytania OPTIONS (CORS Preflight)

OPTIONS /pricing/calculate

Obsługiwane w celu prawidłowych zapytań CORS (Cross-Origin Resource Sharing).

• Metoda OPTIONS zwraca nagłówki:
  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type
• Odpowiedź na OPTIONS ma status HTTP 204 (No Content) i nie zawiera treści.
• Dzięki temu przeglądarki mogą poprawnie wykonać tzw. "preflight" przed wysłaniem zapytania POST z innej domeny.
• To zapytanie jest automatycznie wysyłane przez przeglądarki przed wysłaniem właściwego żądania POST, aby sprawdzić uprawnienia cross-origin.