shopPRO/docs/API.md

# 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)