ver. 0.296: REST API for ordersPRO — orders management, dictionaries, API key auth

- New API layer: ApiRouter, OrdersApiController, DictionariesApiController - Orders API: list (with filters/pagination/updated_since), details, change status, set paid/unpaid - Dictionaries API: order statuses, transport methods, payment methods - X-Api-Key authentication via pp_settings.api_key - OrderRepository: listForApi(), findForApi(), touchUpdatedAt() - updated_at column on pp_shop_orders for polling support - api.php: skip session for API requests, route to ApiRouter - SettingsController: api_key field in system tab - 30 new tests (666 total, 1930 assertions) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-19 20:25:07 +01:00
parent 21efe28464
commit 9cac0d1eeb
22 changed files with 1457 additions and 54 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -0,0 +1,198 @@
+# shopPRO REST API
+
+REST API do integracji z ordersPRO i innymi systemami zewnetrznymi.
+
+## Autentykacja
+
+Kazde zapytanie wymaga headera `X-Api-Key` z kluczem API.
+
+```
+X-Api-Key: {klucz_api}
+```
+
+Klucz przechowywany jest w `pp_settings` jako parametr `api_key`. API jest stateless (bez sesji).
+
+## Format odpowiedzi
+
+### Sukces (HTTP 200)
+```json
+{
+  "status": "ok",
+  "data": { ... }
+}
+```
+
+### Blad
+```json
+{
+  "status": "error",
+  "code": "UNAUTHORIZED",
+  "message": "Invalid or missing API key"
+}
+```
+
+Kody bledow:
+| Kod | HTTP | Opis |
+|-----|------|------|
+| `UNAUTHORIZED` | 401 | Brak lub nieprawidlowy klucz API |
+| `BAD_REQUEST` | 400 | Brakujace lub niepoprawne parametry |
+| `NOT_FOUND` | 404 | Nie znaleziono zasobu/endpointu/akcji |
+| `METHOD_NOT_ALLOWED` | 405 | Nieprawidlowa metoda HTTP |
+| `INTERNAL_ERROR` | 500 | Blad wewnetrzny serwera |
+
+## Endpointy
+
+### Zamowienia
+
+#### Lista zamowien
+```
+GET api.php?endpoint=orders&action=list
+```
+
+Parametry filtrowania (opcjonalne):
+| Parametr | Typ | Opis |
+|----------|-----|------|
+| `status` | int | Filtruj po statusie zamowienia |
+| `paid` | int (0/1) | Filtruj po statusie platnosci |
+| `date_from` | date (YYYY-MM-DD) | Zamowienia od daty |
+| `date_to` | date (YYYY-MM-DD) | Zamowienia do daty |
+| `updated_since` | datetime (YYYY-MM-DD HH:MM:SS) | Zamowienia zmodyfikowane od podanej daty (klucz do pollingu) |
+| `number` | string | Szukaj po numerze zamowienia |
+| `client` | string | Szukaj po imieniu, nazwisku lub emailu klienta |
+| `page` | int | Numer strony (domyslnie 1) |
+| `per_page` | int | Wynikow na strone (domyslnie 50, max 100) |
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": {
+    "items": [
+      {
+        "id": 42,
+        "number": "2026/02/001",
+        "date_order": "2026-02-19 10:30:00",
+        "updated_at": "2026-02-19 12:00:00",
+        "status": 4,
+        "paid": 1,
+        "client_name": "Jan",
+        "client_surname": "Kowalski",
+        "client_email": "jan@example.com",
+        "client_phone": "111222333",
+        "client_street": "Testowa 1",
+        "client_postal_code": "00-000",
+        "client_city": "Warszawa",
+        "firm_name": null,
+        "firm_nip": null,
+        "transport": "Kurier DPD",
+        "transport_cost": 15.00,
+        "payment_method": "Przelew bankowy",
+        "summary": 150.00
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "per_page": 50
+  }
+}
+```
+
+#### Szczegoly zamowienia
+```
+GET api.php?endpoint=orders&action=get&id={order_id}
+```
+
+Zwraca pelne dane zamowienia z produktami i historia statusow.
+
+#### Zmiana statusu zamowienia
+```
+PUT api.php?endpoint=orders&action=change_status&id={order_id}
+Content-Type: application/json
+
+{
+  "status_id": 5,
+  "send_email": true
+}
+```
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": {
+    "order_id": 42,
+    "status_id": 5,
+    "changed": true
+  }
+}
+```
+
+#### Oznacz jako oplacone
+```
+PUT api.php?endpoint=orders&action=set_paid&id={order_id}
+```
+
+Opcjonalnie w body: `{"send_email": true}`
+
+#### Oznacz jako nieoplacone
+```
+PUT api.php?endpoint=orders&action=set_unpaid&id={order_id}
+```
+
+### Slowniki
+
+#### Lista statusow zamowien
+```
+GET api.php?endpoint=dictionaries&action=statuses
+```
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": [
+    {"id": 0, "name": "Nowe"},
+    {"id": 1, "name": "Oplacone"},
+    {"id": 4, "name": "W realizacji"},
+    {"id": 6, "name": "Wyslane"}
+  ]
+}
+```
+
+#### Lista metod transportu
+```
+GET api.php?endpoint=dictionaries&action=transports
+```
+
+#### Lista metod platnosci
+```
+GET api.php?endpoint=dictionaries&action=payment_methods
+```
+
+## Polling
+
+Aby pobierac tylko nowe/zmienione zamowienia, uzyj parametru `updated_since`:
+
+```
+GET api.php?endpoint=orders&action=list&updated_since=2026-02-19 12:00:00
+```
+
+Kolumna `updated_at` w `pp_shop_orders` jest aktualizowana automatycznie przy kazdej modyfikacji zamowienia (zmiana statusu, platnosci, edycja danych, tworzenie zamowienia).
+
+## Konfiguracja
+
+Klucz API ustawia sie w panelu admina w ustawieniach sklepu lub bezposrednio w bazie:
+
+```sql
+INSERT INTO pp_settings (param, value) VALUES ('api_key', 'twoj-klucz-api');
+-- lub
+UPDATE pp_settings SET value = 'twoj-klucz-api' WHERE param = 'api_key';
+```
+
+## Architektura
+
+- Entry point: `api.php`
+- Router: `\api\ApiRouter` (`autoload/api/ApiRouter.php`)
+- Kontrolery: `autoload/api/Controllers/`
+  - `OrdersApiController` — zamowienia (5 akcji)
+  - `DictionariesApiController` — slowniki (3 akcje)