# CargoFlow — dokumentacja API v1

Wersja dokumentacji: 1.0 · 12 października 2026

Dokument opracowano na podstawie kodu projektu CargoFlow. Nie stanowi potwierdzenia wdrożenia wszystkich opisanych rozszerzeń na serwerze. Przed integracją uzgodnij dostępność endpointów i migracji z BJ Solutions: kontakt@bjsolutions.pl.

## 1. Adres i autoryzacja

Baza API: `https://cargoflow.app.bjsolutions.pl/api/v1`.
Wszystkie ścieżki w tabelach są względne do tej bazy.

Administrator firmy tworzy klucz w panelu **Import i API**. Klucz jest pokazywany tylko przy utworzeniu, wygasa po roku i może zostać odwołany. Jest związany z firmą i kontem administratora; wyłączenie firmy lub utrata roli ADMIN przez twórcę blokuje dostęp.

Każde żądanie wymaga nagłówka:

```http
Authorization: Bearer <KLUCZ_API>
```

- Klucz odczytowy: GET i HEAD. Klucz z prawem zapisu: również POST.
- PUT, PATCH i DELETE nie są dostępne przez API v1.
- POST wymaga `Content-Type: application/json`.
- Limit: 120 żądań na minutę na adres IP, wspólny dla kluczy z tego adresu. Odpowiedź 429 zawiera `Retry-After: 60`.
- Klucza nie umieszczaj w adresie URL, kodzie przeglądarki ani logach. Przykłady poniżej używają zmiennej środowiskowej `CARGOFLOW_API_KEY` ustawionej po stronie integracji.
- Firma wynika z klucza. Identyfikatory kierowców, spraw i dokumentów muszą należeć do tej firmy.

Przykład cURL (Bash):

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $CARGOFLOW_API_KEY" \
  'https://cargoflow.app.bjsolutions.pl/api/v1/shipments?page=1&page_size=25'
```

## 2. Podstawowe endpointy

| Metoda | Ścieżka | Zastosowanie |
|---|---|---|
| GET | `/shipments` | Lista spraw firmy |
| POST | `/shipments` | Utworzenie sprawy i zlecenie początkowego SMS |
| GET | `/drivers` | Lista kierowców firmy |
| POST | `/drivers` | Utworzenie kierowcy |
| GET | `/workflow/dashboard` | Pulpit i liczniki |
| GET | `/workflow/accounts` | Konta firmy do przypisania opiekuna |
| GET | `/workflow/{id}` | Organizacja sprawy i historia weryfikacji |

### Listy i paginacja

`/shipments` i `/drivers`: `page` od 1 (domyślnie 1), `page_size` od 1 do 100 (domyślnie 25), `q` do 200 znaków.

Odpowiedź:

```json
{"rows": [], "total": 0, "page": 1, "page_size": 25, "total_pages": 1}
```

Sprawy obsługują `documentation` (kody statusów dokumentacji), `billing=true|false`; wiele wartości rozdziel przecinkiem. Sortowanie: `sort=id|sprawa|data|driver|przewoznik|route_text|billing_ready|documentation_status`, `dir=asc|desc`. Domyślnie data malejąco. `q` przeszukuje m.in. numer ST, kierowcę, trasę i tablice, ale nie numer zlecenia klienta. Do tego służy parametr `search` pulpitu w rozszerzonej wersji.

Pulpit ma strony po 25 pozycji i własny kontrakt odpowiedzi. Podstawowe filtry: `action`, `all`, `missing`, `rejected`, `reviewing`, `ready`, `handed`, `overdue`. Po wdrożeniu rozszerzenia pulpitu również `mine`, `today` oraz `search` (do 120 znaków, numer klienta lub ST). Daty terminów są interpretowane w strefie Europe/Warsaw. `mine` odnosi się do konta administratora, który utworzył klucz.

### Utworzenie kierowcy

POST `/drivers`. Wymagane: `first_name`, `last_name`, `carrier`, `phone`. Opcjonalne: `nationality`.

```json
{"first_name":"Jan","last_name":"Przykładowy","carrier":"Przewoźnik Demo","phone":"+48123456789","nationality":"PL"}
```

201: obiekt `message` i `row` z utworzonym kierowcą. W odpowiedzi imię to `name`, nazwisko `surname`, telefon `contact`, narodowość `origin_branch`; nazwy pól wejściowych i wyjściowych różnią się. Tworzenie kierowcy nie obsługuje nagłówka idempotencji — nie ponawiaj go bez sprawdzenia wyniku.

### Utworzenie sprawy

POST `/shipments`. Wymagane: `driver_id`, `route_text` (do 500 znaków), `truck_number`, `trailer_number` (do 40 znaków każde), niepusta tablica `required_documents` z kodami aktywnych typów dokumentów firmy. Kierowca musi wcześniej istnieć.

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $CARGOFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: erp-demo-zlecenie-001' \
  --data '{"driver_id":1,"route_text":"Warszawa – Poznań","truck_number":"DEMO001","trailer_number":"DEMO002","required_documents":[{"code":"CMR"}]}' \
  'https://cargoflow.app.bjsolutions.pl/api/v1/shipments'
```

Użyj rzeczywistego ID i kodu dokumentu swojej firmy. To operacja zapisu: może utworzyć sprawę, zużyć limit i zlecić płatny SMS. Utworzenie sprawy nie oznacza doręczenia SMS — wiadomość jest przetwarzana przez kolejkę.

201: JSON zawiera m.in. `ok`, `id`, `shipment_id`, `sprawa`, dane sprawy i formularza oraz `sms` (metadane wiadomości lub null). Link formularza umożliwia dostęp kierowcy — traktuj go jako poufny.

Opcjonalne pola procesu wymagają odpowiedniej migracji: `customer_reference` (numer klienta, do 120 znaków), `customer_key` (klucz wyboru wymagań klienta, do 120 znaków), `delivery_date` i `due_date` w formacie YYYY-MM-DD. Daty muszą być poprawnymi datami kalendarzowymi.

**Idempotencja:** zapisz trwale `Idempotency-Key` (do 120 znaków) dla jednej operacji w obrębie firmy. Powtórzenie tych samych danych z tym samym kluczem zwraca 200, `replayed=true` i ten sam ID. Nie zwraca ponownie tokenu formularza. Zmiana danych z tym samym kluczem zwraca 409. Nagłówek nie jest ogólnym mechanizmem dla wszystkich POST.

## 3. Eksport i paczki — rozszerzenia wymagające migracji

Dostępność poniższych operacji należy potwierdzić dla uruchomionej wersji. Wersjonowane paczki i potwierdzenia odbioru wymagają pełnego wdrożenia procesu rozliczeń; wysyłka wymaga dodatkowo skonfigurowanego odbiorcy.

| Metoda | Ścieżka | Zastosowanie |
|---|---|---|
| GET | `/shipments/{id}/export` | JSON sprawy, sekcji i metadanych plików |
| GET | `/document-files/{id}` | Pobranie pliku z autoryzacją Bearer |
| GET | `/workflow/{id}/packets` | Historia wersji paczek i informacja o konfiguracji celu |
| POST | `/workflow/{id}/packets` | Przygotowanie wersji; JSON `{}`; odpowiedź 201 `{packet}` |
| GET | `/billing-packets/{uuid}/documents.zip` | Pobranie konkretnej wersji ZIP |
| GET | `/billing-packets/{uuid}/events` | Historia zdarzeń paczki |
| GET | `/workflow/{id}/documents.zip` | Przygotowanie/pobranie aktualnej paczki; zapisuje zdarzenie pobrania |
| POST | `/billing-packets/{uuid}/send` | Kolejka wysyłki do skonfigurowanego odbiorcy; JSON `{}`; odpowiedź 202 `{packet}` |
| POST | `/billing-packets/{uuid}/receipt` | Potwierdzenie odbioru przez system |
| POST | `/workflow/{id}/handoff` | Zapis ręcznego przekazania |

Eksport JSON ma `schema: "cargoflow.transport-documents"`, `schema_version: 1`, `exported_at`, `shipment`, `sections` i `efti_certified: false`. Sekcje zawierają `files`, a pliki `download_path`. Pobieraj te ścieżki z tym samym kluczem. Eksport nie jest certyfikowaną wymianą eFTI ani dokumentem e-CMR. Kontroluj wersję schematu. Endpoint plików nie jest interfejsem pobierania oryginału PDF; API nie udostępnia też wysyłania plików przez Bearer.

ZIP wymaga gotowości dokumentacji. Limit przygotowania: 95 MB plików i 5 MB manifestu. Zmiana danych lub dokumentów może wymagać nowej wersji. Szczegółowa zawartość paczki, w tym oryginały PDF, zależy od wdrożonych migracji i rozszerzenia PDF.

Przykład potwierdzenia systemowego (POST receipt, klucz z prawem zapisu):

```json
{"packet_id":"UUID-TAKI-SAM-JAK-W-SCIEZCE","state":"RECEIVED","receipt_id":"ERP-ODBIOR-001"}
```

`state`: tylko RECEIVED lub REJECTED; `receipt_id` niepusty, do 200 znaków; opcjonalny `detail`. Paczka musi oczekiwać odbioru (SENDING, AWAITING_RECEIPT lub UNKNOWN). Identyczne powtórzenie potwierdzenia jest akceptowane, sprzeczna decyzja zwraca 409. Nie wysyłaj AWAITING_RECEIPT do endpointu receipt — ten stan może pochodzić z procesu wysyłki, ale nie jest tu przyjmowany.

Przykład ręcznego przekazania (POST handoff):

```json
{"recipient":"Dział rozliczeń","channel":"PORTAL","note":"Dokumenty przekazano przez portal odbiorcy.","receipt_id":"REC-001"}
```

`recipient`: 1–200 znaków; `channel`: EMAIL, PORTAL, PERSONAL lub OTHER; `note`: 10–1000 znaków; `receipt_id`: opcjonalnie do 200 znaków. Kanał EMAIL oznacza zapis sposobu przekazania, nie automatyczną wysyłkę e-mail przez CargoFlow. Ręczne potwierdzenie nie zastępuje systemowego odbioru.

## 4. Wyjątki biznesowe — rozszerzenie

GET `/workflow/{id}/exceptions`: `{rows}` z historią (do 200 pozycji).
POST tej ścieżki: `action`, `reason` (10–1000 znaków), dla dokumentu `section_id`.
Klucz API ma kontekst USER, nawet gdy tworzy go administrator. Dostępne działania: `unavailable`, `request_waiver`, `request_cancel`. Pierwsze dwa wymagają `section_id`.

Decyzje administratora, takie jak zwolnienie, anulowanie, reklamacja i ponowne otwarcie, nie są dostępne przez ten klucz. Także rozstrzyganie niepewnego odbioru paczki (`resolve`) wymaga administratora w panelu. Nie udostępniaj tych operacji w integracji.

## 5. Import CSV w panelu

Import CSV korzysta z sesji użytkownika panelu, nie z Bearer API. `/db/imports/preview` nie należy do API v1. Integracja serwerowa tworzy sprawy przez POST `/api/v1/shipments`.

CSV: UTF-8 (BOM dozwolony), przecinek lub średnik, do 2 MB i 500 wierszy. Wymagane kolumny: `driver_id`, `route_text`, `truck_number`, `trailer_number`, `required_documents`. Dokumenty rozdzielaj `|`, np. CMR|POD. Opcjonalnie `customer_reference`, `customer_key`, `delivery_date`, `due_date` — zależnie od wdrożenia.

Podgląd nie tworzy spraw. Zapis w panelu przetwarza wiersze osobno, nie jako jedną transakcję. Import może zlecić rzeczywiste SMS; wykonuj go świadomie. Identyczne CSV można ponowić bez duplikowania zapisanych spraw dzięki kluczom generowanym w procesie importu.

## 6. Błędy i ponowienia

| HTTP | Znaczenie / reakcja |
|---|---|
| 400 | Niepoprawne pola lub parametry — popraw dane |
| 401 | Brak, nieważny, wygasły lub odwołany klucz |
| 403 | Brak uprawnień, np. zapis kluczem odczytowym |
| 404 | Nie znaleziono zasobu lub endpointu; sprawdź ID, firmę i wdrożenie |
| 409 | Konflikt danych, stanu paczki, gotowości lub idempotencji |
| 415 | POST bez application/json |
| 429 | Limit żądań — respektuj Retry-After |
| 500 | Błąd serwera — sprawdź wynik przed ponowieniem zapisu |

Błędy zwykle mają JSON `{ "message": "Opis błędu" }`; proxy może zwrócić inny format. Limity planu i gotowość procesu są dodatkowymi warunkami wykonania operacji. Nie traktuj 200 listy spraw ani pola `billing_ready` z eksportu jako dowodu odbioru przez księgowość: sprawdź historię paczki i potwierdzenie.

Po timeoutach nie ponawiaj automatycznie dowolnego POST. Dla tworzenia spraw używaj tego samego klucza idempotencji. Dla paczek odczytaj stan i zdarzenia, zwłaszcza UNKNOWN/AWAITING_RECEIPT, przed kolejną wysyłką. Integrację z odbiorcą, harmonogram i mapowanie danych ustala się osobno.

Dokumentacja nie zawiera prawdziwych kluczy ani danych klientów. Kontakt w sprawie integracji: **kontakt@bjsolutions.pl**.
