feat: Add API functions for product management and validation, including JSON response handling
This commit is contained in:
278
docs/api-public-product-management.md
Normal file
278
docs/api-public-product-management.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# AdsPRO API - Zarzadzanie produktami (publiczna dokumentacja)
|
||||
|
||||
Ten dokument opisuje endpointy HTTP dostepne w `api.php` do zarzadzania danymi produktow.
|
||||
Format jest przygotowany pod integracje automatyczne (AI/agent/workflow).
|
||||
|
||||
## 1. Informacje bazowe
|
||||
|
||||
- Metoda: `GET` lub `POST` (`application/x-www-form-urlencoded` albo query string).
|
||||
- Endpoint bazowy: `https://TWOJA-DOMENA/api.php`
|
||||
- Parametr routingu: `action`
|
||||
- Odpowiedzi: JSON
|
||||
- Kodowanie: UTF-8
|
||||
|
||||
Przyklady zakladaja, ze:
|
||||
- domena: `https://example.com`
|
||||
- klucz API: `YOUR_API_KEY`
|
||||
- klient: `client_id=12`
|
||||
- produkt: `offer_id=SKU-123`
|
||||
|
||||
## 2. Autoryzacja
|
||||
|
||||
Kazdy endpoint produktowy wymaga poprawnego parametru:
|
||||
|
||||
- `api_key` - klucz porownywany z `settings.setting_key = api_key`
|
||||
|
||||
Brak lub zly klucz zwraca:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "error",
|
||||
"message": "Invalid api_key"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP status: `401`
|
||||
|
||||
## 3. Wspolne parametry
|
||||
|
||||
- `offer_id` (string, wymagany) - zewnetrzny identyfikator produktu.
|
||||
- `client_id` (int, wymagany) - lokalny identyfikator klienta.
|
||||
|
||||
Jesli produkt nie istnieje dla pary `offer_id + client_id`, API zwraca:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "error",
|
||||
"message": "Product not found"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP status: `404`
|
||||
|
||||
## 4. Endpointy produktowe
|
||||
|
||||
### 4.1 Ustawienie tytulu produktu
|
||||
|
||||
- `action=product_title_set`
|
||||
- Cel: zapisuje `products.title`
|
||||
|
||||
Parametry:
|
||||
- `api_key` (string, wymagany)
|
||||
- `offer_id` (string, wymagany)
|
||||
- `client_id` (int, wymagany)
|
||||
- `title` (string, opcjonalny)
|
||||
|
||||
Uwagi:
|
||||
- `title` jest przycinany (`trim`).
|
||||
- Pusty `title` ustawia `products.title = NULL` (czyszczenie pola).
|
||||
- Zmiana zapisuje komentarz techniczny w `products_comments`.
|
||||
|
||||
Przyklad:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://example.com/api.php" \
|
||||
-d "action=product_title_set" \
|
||||
-d "api_key=YOUR_API_KEY" \
|
||||
-d "client_id=12" \
|
||||
-d "offer_id=SKU-123" \
|
||||
-d "title=Buty biegowe meskie Air Run 42"
|
||||
```
|
||||
|
||||
Przyklad odpowiedzi:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok",
|
||||
"product_id": 987,
|
||||
"offer_id": "SKU-123",
|
||||
"client_id": 12,
|
||||
"title": "Buty biegowe meskie Air Run 42"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Sprawdzenie, czy tytul byl zmieniony
|
||||
|
||||
- `action=product_title_changed_check`
|
||||
- Cel: sprawdza, czy custom tytul rozni sie od bazowej nazwy produktu
|
||||
|
||||
Logika pola `title_changed`:
|
||||
- `true` gdy `products.title` jest niepuste i inne niz `products.name`
|
||||
- `false` w pozostalych przypadkach
|
||||
|
||||
Parametry:
|
||||
- `api_key` (string, wymagany)
|
||||
- `offer_id` (string, wymagany)
|
||||
- `client_id` (int, wymagany)
|
||||
|
||||
Przyklad:
|
||||
|
||||
```bash
|
||||
curl -G "https://example.com/api.php" \
|
||||
--data-urlencode "action=product_title_changed_check" \
|
||||
--data-urlencode "api_key=YOUR_API_KEY" \
|
||||
--data-urlencode "client_id=12" \
|
||||
--data-urlencode "offer_id=SKU-123"
|
||||
```
|
||||
|
||||
Przyklad odpowiedzi:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok",
|
||||
"product_id": 987,
|
||||
"offer_id": "SKU-123",
|
||||
"client_id": 12,
|
||||
"title_changed": true,
|
||||
"default_name": "Buty Air Run - wariant bazowy",
|
||||
"custom_title": "Buty biegowe meskie Air Run 42"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Ustawienie Google Product Category
|
||||
|
||||
- `action=product_google_category_set`
|
||||
- Cel: zapisuje `products.google_product_category`
|
||||
|
||||
Parametry:
|
||||
- `api_key` (string, wymagany)
|
||||
- `offer_id` (string, wymagany)
|
||||
- `client_id` (int, wymagany)
|
||||
- `google_product_category` (string, opcjonalny)
|
||||
|
||||
Uwagi:
|
||||
- wartosc jest przycinana (`trim`)
|
||||
- pusta wartosc ustawia `NULL` (czyszczenie pola)
|
||||
- zmiana zapisuje komentarz techniczny w `products_comments`
|
||||
|
||||
Przyklad:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://example.com/api.php" \
|
||||
-d "action=product_google_category_set" \
|
||||
-d "api_key=YOUR_API_KEY" \
|
||||
-d "client_id=12" \
|
||||
-d "offer_id=SKU-123" \
|
||||
-d "google_product_category=Apparel & Accessories > Shoes"
|
||||
```
|
||||
|
||||
Przyklad odpowiedzi:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok",
|
||||
"product_id": 987,
|
||||
"offer_id": "SKU-123",
|
||||
"client_id": 12,
|
||||
"google_product_category": "Apparel & Accessories > Shoes"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 Odczyt Google Product Category
|
||||
|
||||
- `action=product_google_category_get`
|
||||
- Cel: odczytuje `products.google_product_category`
|
||||
|
||||
Parametry:
|
||||
- `api_key` (string, wymagany)
|
||||
- `offer_id` (string, wymagany)
|
||||
- `client_id` (int, wymagany)
|
||||
|
||||
Przyklad:
|
||||
|
||||
```bash
|
||||
curl -G "https://example.com/api.php" \
|
||||
--data-urlencode "action=product_google_category_get" \
|
||||
--data-urlencode "api_key=YOUR_API_KEY" \
|
||||
--data-urlencode "client_id=12" \
|
||||
--data-urlencode "offer_id=SKU-123"
|
||||
```
|
||||
|
||||
Przyklad odpowiedzi:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok",
|
||||
"product_id": 987,
|
||||
"offer_id": "SKU-123",
|
||||
"client_id": 12,
|
||||
"google_product_category": "Apparel & Accessories > Shoes"
|
||||
}
|
||||
```
|
||||
|
||||
Jesli kategoria nie jest ustawiona:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok",
|
||||
"product_id": 987,
|
||||
"offer_id": "SKU-123",
|
||||
"client_id": 12,
|
||||
"google_product_category": null
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 Ustawienie custom_label_4 (istniejacy endpoint)
|
||||
|
||||
- `action=product_custom_label_4_set`
|
||||
- Cel: zapisuje `products.custom_label_4`
|
||||
|
||||
Parametry:
|
||||
- `api_key` (string, wymagany)
|
||||
- `offer_id` (string, wymagany)
|
||||
- `client_id` (int, wymagany)
|
||||
- `custom_label_4` (string, opcjonalny)
|
||||
|
||||
Przyklad:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://example.com/api.php" \
|
||||
-d "action=product_custom_label_4_set" \
|
||||
-d "api_key=YOUR_API_KEY" \
|
||||
-d "client_id=12" \
|
||||
-d "offer_id=SKU-123" \
|
||||
-d "custom_label_4=bestseller"
|
||||
```
|
||||
|
||||
Przyklad odpowiedzi:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Walidacja i bledy
|
||||
|
||||
### 5.1 Brak wymaganych parametrow
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "error",
|
||||
"message": "Missing required params: offer_id, client_id"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP status: `422`
|
||||
|
||||
### 5.2 Nieznana akcja
|
||||
|
||||
`api.php` nie zwraca centralnego bledu dla nieznanej `action`.
|
||||
Przy integracji AI zawsze ustawiaj jawnie `action` i weryfikuj, czy odpowiedz to JSON.
|
||||
|
||||
## 6. Zalecany kontrakt dla agentow AI
|
||||
|
||||
- Zawsze wysylaj `api_key`, `action`, `client_id`, `offer_id`.
|
||||
- Po `product_title_set` od razu wywolaj `product_title_changed_check`.
|
||||
- Po `product_google_category_set` od razu wywolaj `product_google_category_get`.
|
||||
- Traktuj `null` jako brak wartosci.
|
||||
- Przy statusach `401`, `404`, `422` przerywaj workflow i zwracaj czytelny blad operatorowi.
|
||||
|
||||
## 7. Minimalny scenariusz end-to-end
|
||||
|
||||
1. Ustaw tytul (`product_title_set`)
|
||||
2. Potwierdz zmiane (`product_title_changed_check`)
|
||||
3. Ustaw kategorie (`product_google_category_set`)
|
||||
4. Odczytaj kategorie (`product_google_category_get`)
|
||||
|
||||
To daje prosty, deterministyczny przeplyw dla automatyzacji AI.
|
||||
Reference in New Issue
Block a user