feat: Add endpoint for optimizing products based on clicks, including client identification and response examples in documentation

docs/api-public-product-management.md

@@ -212,7 +212,99 @@ Jesli kategoria nie jest ustawiona:
 }
 ```
 
-### 4.5 Ustawienie custom_label_4 (istniejacy endpoint)
+### 4.5 Pobranie produktow do optymalizacji
+
+- `action=products_to_optimize`
+- Cel: zwraca liste produktow posortowanych wg klikniec (malejaco), ktore nie maja ustawionego custom tytulu (`title`) lub kategorii Google (`google_product_category`)
+
+Identyfikacja klienta (wymagany dokladnie jeden z trzech):
+- `client_id` (int) - lokalny identyfikator klienta w adsPRO
+- `google_ads_id` (string) - ID konta Google Ads (z myslnikami lub bez, np. `123-456-7890` lub `1234567890`)
+- `merchant_id` (string) - ID konta Google Merchant Center (z myslnikami lub bez)
+
+Parametry dodatkowe:
+- `api_key` (string, wymagany)
+- `limit` (int, opcjonalny) - liczba produktow do zwrocenia (domyslnie 10, max 100)
+
+Logika:
+- Wybiera produkty, ktorych `title` jest pusty/NULL **lub** `google_product_category` jest pusty/NULL
+- Pomija produkty z 0 klikniec (all-time)
+- Sortuje po `clicks_all_time` malejaco (produkty z najwiekszym ruchem na gorze)
+- Agreguje dane z `products_aggregate` (suma klikniec ze wszystkich kampanii/grup reklam)
+
+Przyklad z `client_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=products_to_optimize" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "client_id=12" \
+  --data-urlencode "limit=10"
+```
+
+Przyklad z `google_ads_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=products_to_optimize" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "google_ads_id=123-456-7890"
+```
+
+Przyklad z `merchant_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=products_to_optimize" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "merchant_id=987654321"
+```
+
+Przyklad odpowiedzi:
+
+```json
+{
+  "result": "ok",
+  "client_id": 12,
+  "count": 3,
+  "products": [
+    {
+      "id": 987,
+      "offer_id": "SKU-123",
+      "original_name": "Buty sportowe Nike Air",
+      "custom_title": null,
+      "google_product_category": null,
+      "product_url": "https://example.com/buty-nike-air",
+      "clicks_30": 45,
+      "clicks_all_time": 312,
+      "impressions_30": 1200,
+      "cost_30": "89.500000",
+      "conversions_30": "3.000000",
+      "conversion_value_30": "450.000000"
+    },
+    {
+      "id": 654,
+      "offer_id": "SKU-456",
+      "original_name": "Koszulka Adidas",
+      "custom_title": "Koszulka sportowa Adidas Originals",
+      "google_product_category": null,
+      "product_url": "https://example.com/koszulka-adidas",
+      "clicks_30": 22,
+      "clicks_all_time": 198,
+      "impressions_30": 800,
+      "cost_30": "45.200000",
+      "conversions_30": "1.000000",
+      "conversion_value_30": "120.000000"
+    }
+  ]
+}
+```
+
+Bledy specyficzne:
+- Brak parametru identyfikujacego klienta: `422` z `"Missing required param: client_id, google_ads_id or merchant_id"`
+- Klient nie znaleziony: `404` z `"Client not found"`
+
+### 4.6 Ustawienie custom_label_4 (istniejacy endpoint)
 
 - `action=product_custom_label_4_set`
 - Cel: zapisuje `products.custom_label_4`
@@ -270,9 +362,11 @@ Przy integracji AI zawsze ustawiaj jawnie `action` i weryfikuj, czy odpowiedz to
 
 ## 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`)
+1. Pobierz liste produktow do optymalizacji (`products_to_optimize`)
+2. Dla kazdego produktu z listy:
+   a. Jesli `custom_title` jest `null` - ustaw tytul (`product_title_set`)
+   b. Potwierdz zmiane tytulu (`product_title_changed_check`)
+   c. Jesli `google_product_category` jest `null` - ustaw kategorie (`product_google_category_set`)
+   d. Odczytaj kategorie (`product_google_category_get`)
 
 To daje prosty, deterministyczny przeplyw dla automatyzacji AI.