Frazy: słowa kluczowe grupy (`getGroupKeywords`)

POST/api/rank_tracker/reports/keywords/getGroupKeywords

Zwraca lekką listę słów kluczowych należących do wskazanej grupy w projekcie Rank Tracker. Każdy element to wyłącznie id słowa kluczowego oraz jego nazwa (keyword) — bez danych o pozycjach czy statystykach (te udostępnia osobna akcja, np. getData w tym samym kontrolerze). Wynik jest stronicowany.

Fraza	ID
jak wychować szczeniaka	690709
karma dla szczeniaka maltańczyka	704922

projekt i grupa Rank Trackera, limit: 2, strona 2. Każdy wiersz to wyłącznie para id + keyword. Wszystkie adresowalne pola wiersza.

Żądanie

POST /api/rank_tracker/reports/keywords/getGroupKeywords

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "project_id": null,
  "group_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "project_id": null,
  "group_id": null,
  "limit": 2,
  "page": 2
}

cURL


curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/keywords/getGroupKeywords' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "group_id": null, "limit": 2, "page": 2 }'

Parametry

Name	Type	Default
`project_id`	`number` Wymagane. ID projektu Rank Tracker. Jedyne pole twardo wymagane przez walidator (`ProjectAccessRules::requirePresence`). Musi należeć do użytkownika (lub być udostępnione przez `AclUsersRoles`), inaczej zwracane jest `Unauthorized access`. Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`group_id`	`number` Wymagane. ID grupy słów kluczowych w projekcie. Formalnie nie jest wymuszane przez `requirePresence`, ale bez niego zapytanie filtruje po `group_id = null` i zwraca pustą listę (`data: []`, `count: 0`) z `HTTP 200` — więc funkcjonalnie jest wymagane. Listę grup pobierzesz z `GET /api/rank_tracker/management/groups/list?project_id=<id>`. `group_id` musi należeć do podanego `project_id`, inaczej zwracane jest `Unauthorized access`.
`limit`	`number` Rozmiar strony paginacji (nieujemna liczba całkowita, `maxLimit = 100`). Odbija się w `pagination.limit`.	`10`
`page`	`number` Numer strony paginacji (nieujemna liczba całkowita).	`1`

Choć group_id nie jest wymuszane przez walidator (requirePresence działa dla niego warunkowo — tylko gdy pole już jest w danych), w praktyce zawsze je podawaj: bez group_id otrzymasz HTTP 200 z pustą listą, a nie błąd. Podanie group_id nienależącego do project_id skutkuje Unauthorized access.

Endpoint obsługuje wyłącznie metodę POST — parametry przekazuj w ciele żądania (getData() czyta body zarówno w walidatorze, jak i w warunku WHERE GroupsKeywords.group_id). Pułapka: ten sam URL wywołany przez GET zwraca HTTP 200, ale zawsze data: [] i count: 0 — nawet z poprawnym project_id/group_id w query stringu — ponieważ przy GET ciało jest puste, a filtr leci po group_id = null. Twardo wymagane jest tylko project_id; brak group_id nie powoduje błędu walidacji, lecz zwraca pustą listę z HTTP 200, więc funkcjonalnie group_id jest również wymagane. Brak project_id → 418 z invalid_data.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę słów kluczowych grupy) oraz pagination. Każdy element data zawiera wyłącznie id (liczba całkowita) i keyword (nazwa frazy). count w pagination odzwierciedla rzeczywistą liczbę słów kluczowych w grupie.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "id": 690709, "keyword": "jak wychować szczeniaka" }
  ],
  "pagination": { "page_count": 31, "current_page": 2, "has_next_page": true, "has_prev_page": true, "count": 62, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`GroupKeyword[]` Słowa kluczowe należące do grupy
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number \| null; }` Metadane paginacji

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

418 jest zwracane również w przypadku błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Brak project_id → {"success":false,"data":{"error":{"type":"invalid_data","params":{"project_id":{"_required":"This field is required"},"group_id":{"unauthorized":"Unauthorized access"}}}}} (bez project_id nie da się potwierdzić dostępu do grupy). Cudzy lub nieistniejący project_id / group_id zwraca Unauthorized access (418), a nie 404. Konto administratora (role_id = 1) omija obie kontrole dostępu.

Powiązane akcje

getGroupKeywords — lekka lista (id + keyword) ograniczona do jednej grupy (ta strona)
getProjectKeywords — słowa kluczowe całego projektu (POST, project_id, bez group_id)
getData — pełne statystyki pozycji (POST, project_id + group_id + filtering + order)
getSerpHtml — zapis HTML wyników SERP (POST, keyword_id + date + project_id)
getBestKeywords / getProjectsStatus — pozostałe akcje pomocnicze kontrolera

Frazy: słowa kluczowe grupy (getGroupKeywords)