feat: Add API endpoints for retrieving minimum ROAS of products and average minimum ROAS for clients, including detailed documentation

2026-03-10 01:00:26 +01:00
parent ba90f22904
commit 595bb574f0
3 changed files with 271 additions and 8 deletions
--- a/docs/api-public-product-management.md
+++ b/docs/api-public-product-management.md
@@ -334,6 +334,127 @@ Przyklad odpowiedzi:
 }
 ```

+### 4.7 Odczyt minimalnego ROAS produktu
+
+- `action=product_min_roas_get`
+- Cel: odczytuje `products.min_roas` dla wskazanego produktu
+
+Identyfikacja produktu (wymagany dokladnie jeden z dwoch):
+- `product_id` (int) - wewnetrzny identyfikator produktu w adsPRO (`products.id`)
+- `google_ads_product_id` (string) - zewnetrzny identyfikator produktu z Google Ads (mapowany do `products.offer_id`)
+
+Parametry dodatkowe:
+- `api_key` (string, wymagany)
+
+Przyklad z `product_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=product_min_roas_get" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "product_id=987"
+```
+
+Przyklad z `google_ads_product_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=product_min_roas_get" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "google_ads_product_id=SKU-123"
+```
+
+Przyklad odpowiedzi:
+
+```json
+{
+  "result": "ok",
+  "product_id": 987,
+  "offer_id": "SKU-123",
+  "min_roas": 450
+}
+```
+
+Jesli minimalny ROAS nie jest ustawiony:
+
+```json
+{
+  "result": "ok",
+  "product_id": 987,
+  "offer_id": "SKU-123",
+  "min_roas": null
+}
+```
+
+Bledy specyficzne:
+- Brak identyfikatora produktu: `422` z `"Missing required param: product_id or google_ads_product_id"`
+- Podano oba identyfikatory jednoczesnie: `422` z `"Provide only one identifier: product_id or google_ads_product_id"`
+- Produkt nie znaleziony: `404` z `"Product not found"`
+
+### 4.8 Odczyt sredniego minimalnego ROAS dla klienta
+
+- `action=client_avg_min_roas_get`
+- Cel: zwraca sredni `min_roas` dla produktow danego klienta
+
+Identyfikacja klienta (wymagany dokladnie jeden z dwoch):
+- `client_id` (int) - wewnetrzny identyfikator klienta w adsPRO
+- `google_ads_id` (string) - ID konta Google Ads (z myslnikami lub bez)
+
+Parametry dodatkowe:
+- `api_key` (string, wymagany)
+
+Logika:
+- Srednia liczona jest z `products.min_roas`
+- Do sredniej wchodza tylko produkty z ustawionym `min_roas` (`IS NOT NULL`)
+- Gdy brak produktow z ustawionym `min_roas`, `avg_min_roas` zwracane jest jako `null`
+
+Przyklad z `client_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=client_avg_min_roas_get" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "client_id=12"
+```
+
+Przyklad z `google_ads_id`:
+
+```bash
+curl -G "https://example.com/api.php" \
+  --data-urlencode "action=client_avg_min_roas_get" \
+  --data-urlencode "api_key=YOUR_API_KEY" \
+  --data-urlencode "google_ads_id=123-456-7890"
+```
+
+Przyklad odpowiedzi:
+
+```json
+{
+  "result": "ok",
+  "client_id": 12,
+  "google_ads_id": "123-456-7890",
+  "products_with_min_roas": 24,
+  "avg_min_roas": 436.25
+}
+```
+
+Jesli klient nie ma ustawionego `min_roas` na zadnym produkcie:
+
+```json
+{
+  "result": "ok",
+  "client_id": 12,
+  "google_ads_id": "123-456-7890",
+  "products_with_min_roas": 0,
+  "avg_min_roas": null
+}
+```
+
+Bledy specyficzne:
+- Brak identyfikatora klienta: `422` z `"Missing required param: client_id or google_ads_id"`
+- Podano oba identyfikatory jednoczesnie: `422` z `"Provide only one identifier: client_id or google_ads_id"`
+- Klient nie znaleziony: `404` z `"Client not found"`
+
 ## 5. Walidacja i bledy

 ### 5.1 Brak wymaganych parametrow