367 lines
8.0 KiB
Markdown
367 lines
8.0 KiB
Markdown
# 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}
|
|
```
|
|
|
|
### Produkty
|
|
|
|
#### Lista produktow
|
|
```
|
|
GET api.php?endpoint=products&action=list
|
|
```
|
|
|
|
Parametry filtrowania (opcjonalne):
|
|
| Parametr | Typ | Opis |
|
|
|----------|-----|------|
|
|
| `search` | string | Szukaj po nazwie, EAN lub SKU |
|
|
| `status` | int (0/1) | Filtruj po statusie (1 = aktywny, 0 = nieaktywny) |
|
|
| `promoted` | int (0/1) | Filtruj po promocji |
|
|
| `sort` | string | Sortuj po: id, name, price_brutto, status, promoted, quantity (domyslnie id) |
|
|
| `sort_dir` | string | Kierunek: ASC lub DESC (domyslnie DESC) |
|
|
| `page` | int | Numer strony (domyslnie 1) |
|
|
| `per_page` | int | Wynikow na strone (domyslnie 50, max 100) |
|
|
|
|
Odpowiedz:
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"id": 1,
|
|
"sku": "PROD-001",
|
|
"ean": "5901234123457",
|
|
"name": "Produkt testowy",
|
|
"price_brutto": 99.99,
|
|
"price_brutto_promo": null,
|
|
"price_netto": 81.29,
|
|
"price_netto_promo": null,
|
|
"quantity": 10,
|
|
"status": 1,
|
|
"promoted": 0,
|
|
"vat": 23,
|
|
"weight": 0.5,
|
|
"main_image": "product1.jpg",
|
|
"date_add": "2026-01-15 10:00:00",
|
|
"date_modify": "2026-02-19 12:00:00"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"page": 1,
|
|
"per_page": 50
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Szczegoly produktu
|
|
```
|
|
GET api.php?endpoint=products&action=get&id={product_id}
|
|
```
|
|
|
|
Zwraca pelne dane produktu z jezykami, zdjeciami, kategoriami i atrybutami.
|
|
|
|
Odpowiedz:
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"data": {
|
|
"id": 1,
|
|
"sku": "PROD-001",
|
|
"ean": "5901234123457",
|
|
"price_brutto": 99.99,
|
|
"price_brutto_promo": null,
|
|
"price_netto": 81.29,
|
|
"price_netto_promo": null,
|
|
"quantity": 10,
|
|
"status": 1,
|
|
"promoted": 0,
|
|
"vat": 23,
|
|
"weight": 0.5,
|
|
"stock_0_buy": 0,
|
|
"custom_label_0": null,
|
|
"set_id": null,
|
|
"product_unit_id": 1,
|
|
"producer_id": 3,
|
|
"date_add": "2026-01-15 10:00:00",
|
|
"date_modify": "2026-02-19 12:00:00",
|
|
"languages": {
|
|
"pl": {
|
|
"name": "Produkt testowy",
|
|
"short_description": "Krotki opis",
|
|
"description": "<p>Pelny opis produktu</p>",
|
|
"meta_description": null,
|
|
"meta_keywords": null,
|
|
"meta_title": null,
|
|
"seo_link": "produkt-testowy",
|
|
"copy_from": null,
|
|
"warehouse_message_zero": null,
|
|
"warehouse_message_nonzero": null,
|
|
"tab_name_1": null,
|
|
"tab_description_1": null,
|
|
"tab_name_2": null,
|
|
"tab_description_2": null,
|
|
"canonical": null
|
|
}
|
|
},
|
|
"images": [
|
|
{"id": 1, "src": "product1.jpg", "alt": "Zdjecie produktu"}
|
|
],
|
|
"categories": [1, 5],
|
|
"attributes": [
|
|
{"attribute_id": 1, "value_id": 3}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Tworzenie produktu
|
|
```
|
|
POST api.php?endpoint=products&action=create
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"price_brutto": 99.99,
|
|
"vat": 23,
|
|
"quantity": 10,
|
|
"status": 1,
|
|
"sku": "PROD-001",
|
|
"ean": "5901234123457",
|
|
"weight": 0.5,
|
|
"languages": {
|
|
"pl": {
|
|
"name": "Nowy produkt",
|
|
"description": "<p>Opis produktu</p>"
|
|
}
|
|
},
|
|
"categories": [1, 5],
|
|
"products_related": [10, 20]
|
|
}
|
|
```
|
|
|
|
Wymagane: `languages` (min. 1 jezyk z `name`) oraz `price_brutto`.
|
|
|
|
Odpowiedz (HTTP 201):
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"data": {
|
|
"id": 42
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Aktualizacja produktu
|
|
```
|
|
PUT api.php?endpoint=products&action=update&id={product_id}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"price_brutto": 129.99,
|
|
"status": 1,
|
|
"languages": {
|
|
"pl": {
|
|
"name": "Zaktualizowana nazwa"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Partial update — wystarczy przeslac tylko zmienione pola. Pola nieprzeslane zachowuja aktualna wartosc.
|
|
|
|
Odpowiedz: pelne dane produktu (jak w `get`).
|
|
|
|
### 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)
|
|
- `ProductsApiController` — produkty (4 akcje: list, get, create, update)
|
|
- `DictionariesApiController` — slowniki (3 akcje)
|