update
This commit is contained in:
Jacek
@@ -1,3 +1,255 @@
|
||||
# API
|
||||
|
||||
> Endpointy, kontrakty request/response, autentykacja.
|
||||
## Scope
|
||||
|
||||
Dokument opisuje aktualne REST API dostepne przez `api.php` (ordersPRO + slowniki + produkty + kategorie).
|
||||
|
||||
## Base URL
|
||||
|
||||
- Endpoint techniczny: `/api.php`
|
||||
- Routing odbywa sie przez query params:
|
||||
- `endpoint` (np. `orders`, `products`)
|
||||
- `action` (np. `list`, `get`)
|
||||
|
||||
Przyklad:
|
||||
|
||||
```text
|
||||
GET /api.php?endpoint=orders&action=list
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
- Wymagany naglowek: `X-Api-Key: <api_key>`
|
||||
- Klucz jest porownywany z wartoscia `pp_settings.api_key`
|
||||
- Brak lub zly klucz:
|
||||
- HTTP `401`
|
||||
- payload:
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or missing API key"
|
||||
}
|
||||
```
|
||||
|
||||
## Response format
|
||||
|
||||
Sukces:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
Blad:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"code": "BAD_REQUEST",
|
||||
"message": "..."
|
||||
}
|
||||
```
|
||||
|
||||
## Common HTTP/logic errors
|
||||
|
||||
- `400 BAD_REQUEST` - brak wymaganych parametrow/body
|
||||
- `401 UNAUTHORIZED` - brak/zly API key
|
||||
- `404 NOT_FOUND` - nieznany endpoint/action lub brak rekordu
|
||||
- `405 METHOD_NOT_ALLOWED` - zla metoda HTTP
|
||||
- `500 INTERNAL_ERROR` - blad serwera
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Orders (`endpoint=orders`)
|
||||
|
||||
- `GET action=list`
|
||||
- filtry (opcjonalne): `status`, `paid`, `date_from`, `date_to`, `updated_since`, `number`, `client`
|
||||
- paginacja: `page` (default 1), `per_page` (default 50, max 100)
|
||||
- `GET action=get&id={id}`
|
||||
- `PUT action=change_status&id={id}`
|
||||
- body JSON:
|
||||
- `status_id` (required, int)
|
||||
- `send_email` (optional, bool)
|
||||
- `PUT action=set_paid&id={id}`
|
||||
- body JSON optional: `send_email` (bool)
|
||||
- `PUT action=set_unpaid&id={id}`
|
||||
|
||||
### Products (`endpoint=products`)
|
||||
|
||||
- `GET action=list`
|
||||
- filtry:
|
||||
- `search`, `status`, `promoted`
|
||||
- `attribute_{attributeId}={valueId}` (np. `attribute_12=37`)
|
||||
- sortowanie: `sort` (default `id`), `sort_dir` (default `DESC`)
|
||||
- paginacja: `page`, `per_page` (max 100)
|
||||
- `GET action=get&id={id}`
|
||||
- `POST action=create`
|
||||
- wymagane minimum:
|
||||
- `languages` (array, co najmniej jeden jezyk z `name`)
|
||||
- `price_brutto` (number >= 0)
|
||||
- `PUT action=update&id={id}`
|
||||
- partial update przez JSON body
|
||||
- `GET action=variants&id={parentProductId}`
|
||||
- dla produktu glownego (nie wariantu)
|
||||
- `POST action=create_variant&id={parentProductId}`
|
||||
- body:
|
||||
- `attributes` (required array)
|
||||
- opcjonalnie pola wariantu (np. `price_brutto`, `quantity`, `sku`, ...)
|
||||
- `PUT action=update_variant&id={variantId}`
|
||||
- partial update wariantu
|
||||
- `DELETE action=delete_variant&id={variantId}`
|
||||
- `POST action=upload_image`
|
||||
- body:
|
||||
- `id` (product id, required)
|
||||
- `file_name` (required)
|
||||
- `content_base64` (required)
|
||||
- `alt` (optional)
|
||||
- `o` (optional position)
|
||||
|
||||
### Dictionaries (`endpoint=dictionaries`)
|
||||
|
||||
- `GET action=statuses`
|
||||
- `GET action=transports`
|
||||
- `GET action=payment_methods`
|
||||
- `GET action=attributes`
|
||||
- `POST action=ensure_attribute`
|
||||
- body: `name` (required), `type` (optional int), `lang` (optional, default `pl`)
|
||||
- `POST action=ensure_attribute_value`
|
||||
- body: `attribute_id` (required), `name` (required), `lang` (optional, default `pl`)
|
||||
- `POST action=ensure_producer`
|
||||
- body: `name` (required)
|
||||
|
||||
### Categories (`endpoint=categories`)
|
||||
|
||||
- `GET action=list`
|
||||
- zwraca aktywne kategorie w formie flat list:
|
||||
- `id`
|
||||
- `parent_id`
|
||||
- `title`
|
||||
- tytuly pobierane najpierw w jezyku domyslnym (`pp_langs.start=1`), potem fallback.
|
||||
|
||||
## Source of truth (mapa API w kodzie)
|
||||
|
||||
### 1) Wejscie i dispatch
|
||||
|
||||
- `api.php`
|
||||
- wykrywa request API przez `$_GET['endpoint']`
|
||||
- ustawia JSON content-type
|
||||
- tworzy `medoo` + `SettingsRepository`
|
||||
- przekazuje sterowanie do `\api\ApiRouter::handle()`
|
||||
- `autoload/api/ApiRouter.php`
|
||||
- autentykacja (`X-Api-Key` vs `pp_settings.api_key`)
|
||||
- walidacja `endpoint` i `action`
|
||||
- mapowanie endpoint -> kontroler (`getControllerFactories()`)
|
||||
- helpery odpowiedzi: `sendSuccess()`, `sendError()`
|
||||
- helpery requestu: `getJsonBody()`, `requireMethod()`
|
||||
|
||||
### 2) Endpointy i kontrolery (runtime source)
|
||||
|
||||
#### `endpoint=orders`
|
||||
|
||||
- plik: `autoload/api/Controllers/OrdersApiController.php`
|
||||
- akcje:
|
||||
- `list` (GET)
|
||||
- `get` (GET)
|
||||
- `change_status` (PUT)
|
||||
- `set_paid` (PUT)
|
||||
- `set_unpaid` (PUT)
|
||||
|
||||
#### `endpoint=products`
|
||||
|
||||
- plik: `autoload/api/Controllers/ProductsApiController.php`
|
||||
- akcje:
|
||||
- `list` (GET)
|
||||
- `get` (GET)
|
||||
- `create` (POST)
|
||||
- `update` (PUT)
|
||||
- `variants` (GET)
|
||||
- `create_variant` (POST)
|
||||
- `update_variant` (PUT)
|
||||
- `delete_variant` (DELETE)
|
||||
- `upload_image` (POST)
|
||||
|
||||
#### `endpoint=dictionaries`
|
||||
|
||||
- plik: `autoload/api/Controllers/DictionariesApiController.php`
|
||||
- akcje:
|
||||
- `statuses` (GET)
|
||||
- `transports` (GET)
|
||||
- `payment_methods` (GET)
|
||||
- `attributes` (GET)
|
||||
- `ensure_attribute` (POST)
|
||||
- `ensure_attribute_value` (POST)
|
||||
- `ensure_producer` (POST)
|
||||
|
||||
#### `endpoint=categories`
|
||||
|
||||
- plik: `autoload/api/Controllers/CategoriesApiController.php`
|
||||
- akcje:
|
||||
- `list` (GET)
|
||||
|
||||
### 3) Warstwa domenowa pod API (shape danych)
|
||||
|
||||
- Orders:
|
||||
- `Domain\Order\OrderRepository::listForApi()`
|
||||
- `Domain\Order\OrderRepository::findForApi()`
|
||||
- `Domain\Order\OrderAdminService` (zmiana statusu/platnosci)
|
||||
- Products:
|
||||
- `Domain\Product\ProductRepository::listForApi()`
|
||||
- `Domain\Product\ProductRepository::findForApi()`
|
||||
- `Domain\Product\ProductRepository::saveProduct()`
|
||||
- metody wariantow `*VariantForApi()`
|
||||
- Dictionaries:
|
||||
- `Domain\ShopStatus\ShopStatusRepository`
|
||||
- `Domain\Transport\TransportRepository`
|
||||
- `Domain\PaymentMethod\PaymentMethodRepository`
|
||||
- `Domain\Attribute\AttributeRepository`
|
||||
- `Domain\Producer\ProducerRepository`
|
||||
- Categories:
|
||||
- bezposrednio query przez `$GLOBALS['mdb']` w `CategoriesApiController`
|
||||
|
||||
### 4) Testy API (behavior source)
|
||||
|
||||
- `tests/Unit/api/ApiRouterTest.php`
|
||||
- `tests/Unit/api/Controllers/OrdersApiControllerTest.php`
|
||||
- `tests/Unit/api/Controllers/ProductsApiControllerTest.php`
|
||||
- `tests/Unit/api/Controllers/DictionariesApiControllerTest.php`
|
||||
|
||||
### 5) Dokumentacja kontraktu (human source)
|
||||
|
||||
- `api-docs/api-reference.json`
|
||||
- `api-docs/index.html`
|
||||
|
||||
Uwaga: dokumentacja z `api-docs/*` moze byc starsza od runtime.
|
||||
Zrodlem prawdy dla dzialania endpointow jest zawsze:
|
||||
`api.php` + `autoload/api/ApiRouter.php` + aktualne kontrolery `autoload/api/Controllers/*`.
|
||||
|
||||
## Curl examples
|
||||
|
||||
Pobranie listy zamowien:
|
||||
|
||||
```bash
|
||||
curl -X GET "https://example.com/api.php?endpoint=orders&action=list&page=1&per_page=20" \
|
||||
-H "X-Api-Key: YOUR_API_KEY"
|
||||
```
|
||||
|
||||
Zmiana statusu zamowienia:
|
||||
|
||||
```bash
|
||||
curl -X PUT "https://example.com/api.php?endpoint=orders&action=change_status&id=123" \
|
||||
-H "X-Api-Key: YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"status_id\": 6, \"send_email\": true}"
|
||||
```
|
||||
|
||||
Dodanie wariantu produktu:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://example.com/api.php?endpoint=products&action=create_variant&id=50" \
|
||||
-H "X-Api-Key: YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"attributes\":[{\"attribute_id\":12,\"attribute_value_id\":37}],\"price_brutto\":99.99,\"quantity\":10}"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user