REST API v1

Programowy dostęp do Twoich klientów, stron, grup i słów. Działa równolegle z panelem — co zrobisz przez API, zobaczysz natychmiast w UI i na odwrót.

Logowanie

Każde żądanie wymaga nagłówka X-API-Token: TWÓJ_TOKEN.

API jest domyślnie wyłączone. Aby je włączyć i otrzymać token, napisz na kontakt@pozycjosprawdzator.pl — odpiszemy z tokenem w ciągu 24h.

Token traktuj jak hasło: nie wklejaj do publicznego kodu. Jeśli wyciekł, napisz do nas — zrobimy rotację (stary natychmiast przestanie działać).

curl -H "X-API-Token: TWÓJ_TOKEN" \
     https://tutaj.pozycjosprawdzator.pl/api/v1/me

Endpointy

Każdy zasób (klient, strona, grupa, słowo) ma pełny CRUD.

Metoda	Endpoint	Co robi
GET	/api/v1/me	Twoje dane: id, e-mail, limit, zużycie
GET	/api/v1/clients	Lista klientów (paginacja: `?page=1&per_page=50`)
GET	/api/v1/clients/{id}	Szczegóły klienta
POST	/api/v1/clients	Nowy klient: `{"name":"...","notes":"..."}`
PUT	/api/v1/clients/{id}	Edycja: `{"name":"..."}`
DELETE	/api/v1/clients/{id}	Usunięcie
Strony WWW
GET	/api/v1/sites?client_id=N	Lista stron (z filtrowaniem po kliencie)
POST	/api/v1/sites	`{"client_id":1,"domain":"example.pl"}`
PUT	/api/v1/sites/{id}	Edycja domain/match_type/client_id
DELETE	/api/v1/sites/{id}	Usunięcie
Grupy słów
GET	/api/v1/groups?site_id=N	Lista grup
POST	/api/v1/groups	`{"site_id":1,"name":"Lokalne","country_code":"pl","freq_value":1,"freq_unit":"week","use_maps":true}`
PUT	/api/v1/groups/{id}	Pełna edycja parametrów grupy
DELETE	/api/v1/groups/{id}	Usunięcie grupy + wszystkich słów
Słowa kluczowe
GET	/api/v1/keywords?group_id=N	Lista słów + ostatni pomiar
GET	/api/v1/keywords/{id}/history	Pełna historia pomiarów
POST	/api/v1/keywords	`{"group_id":1,"keywords":["s1","s2"]}` (lista lub jedno `"keyword"`)
PUT	/api/v1/keywords/{id}	Edycja: `{"keyword":"...","active":true}`
DELETE	/api/v1/keywords/{id}	Usunięcie słowa
Sprawdzenia
POST	/api/v1/check/group/{id}	Uruchom sprawdzenie grupy (asynchronicznie)
POST	/api/v1/check/keyword/{id}	Uruchom sprawdzenie pojedynczego słowa
GET	/api/v1/runs?limit=50	Historia uruchomień + statusy
Pomiary (rankings)
PUT	/api/v1/rankings/{id}	Ręczna korekta pomiaru: `{"organic_pos":3,"maps_pos":1,"ads_pos":null,"edit_note":"..."}` — pole `null` lub pominięte = bez zmiany; pusty string lub `"brak"` = ustaw na brak.

Przykład: dodać 10 słów do grupy

curl -X POST https://tutaj.pozycjosprawdzator.pl/api/v1/keywords \
     -H "X-API-Token: TWÓJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"group_id": 5, "keywords": ["plakatowanie warszawa", "rozwieszanie plakatów", "..."]}'

Przykład: pobrać raport CSV (przez panel)

Eksporty CSV są dostępne w panelu (przyciski w widokach klienta, strony, grupy i raportu) — to nie API, ale działa również z cookie sesji w przeglądarce.

Bezpieczeństwo i limity

Token wystawiamy na życzenie. W dowolnej chwili możesz napisać po rotację albo wyłączenie.
Każde uruchomione sprawdzenie liczy się do Twojego miesięcznego limitu (tak jak w panelu).
API jest multi-tenant: widzisz wyłącznie swoje konta klienckie. Próba dostępu do cudzego klienta zwraca 403.
Endpointy mutujące (POST/PUT/DELETE) wymagają Content-Type: application/json.
W razie błędu zwracamy JSON z polem detail i status HTTP 4xx/5xx.