Instrukcja obsługi

1. Wstęp — co to jest Pozycjosprawdzator?

Pozycjosprawdzator codziennie sprawdza, gdzie Twoje strony znajdują się w wynikach Google — w wynikach organicznych, w Wizytówkach Google (mapy / wyniki lokalne) oraz w reklamach Google Ads. Trzy źródła w jednym narzędziu.

Sprawdzanie odbywa się z serwera, nie z Twojej przeglądarki — Google nie pokazuje spersonalizowanych wyników, więc widzisz „neutralną" pozycję. Wybierasz kraj i ewentualnie miasto, system pyta Google: „udawaj, że jesteś w Warszawie i nikogo nie znasz".

2. Logowanie

Strona logowania: /login.

1. Wpisz e-mail otrzymany od administratora.
2. Wpisz hasło (min. 8 znaków). Pierwsze hasło dostajesz mailem — zmień je przy okazji w sekcji „Zapomniałem hasła".
3. Sesja trwa 30 dni — nie musisz się logować codziennie z tego samego komputera.

Zapomniałeś hasła? Kliknij „Zapomniałem hasła" i dostaniesz mailem link do zmiany — ważny przez 2 godziny.

3. Hierarchia: klient → strona → grupa → słowo

Wszystko co śledzisz układa się w cztery poziomy:

Klikasz w klienta — widzisz strony. Klikasz w stronę — widzisz grupy. Klikasz w grupę — widzisz słowa. Klikasz w słowo — widzisz pełną historię.

4. Dashboard (pulpit)

Główny ekran pokazuje:

• Sześć kafelków KPI — ile słów masz w TOP 1, TOP 3, TOP 10, TOP 50, TOP 100 i ile w ogóle nie pojawia się w wynikach.
• Listę klientów — z liczbami stron / grup / słów. Każdy klient ma przyciski „raport" i „sprawdź".
• Ostatnie sprawdzenia w sidebarze po prawej — szybki podgląd, co się dzieje na bieżąco.

5. Sprawdzanie pozycji

Automatyczne (cron)

Każda grupa ma częstotliwość: „co 1 dzień", „co 2 tygodnie", „co 1 miesiąc" lub „ręcznie". System co noc o 00:05 sprawdza, które grupy są „due" i uruchamia sprawdzenie. Rano masz świeże dane.

Częstotliwość ustawiasz przy edycji grupy: liczba + jednostka (np. 4 + dzień = co 4 dni).

Ręczne (przyciski ▶ Sprawdź)

• Cały portfel — przycisk „Sprawdź pozycje" w prawym górnym rogu (sprawdza wszystkie aktywne słowa).
• Pojedynczy klient — przycisk „▶ sprawdź" przy kliencie na dashboardzie albo „▶ Sprawdź wszystko" na stronie klienta.
• Pojedyncza grupa — przycisk „▶ Sprawdź grupę" na ekranie grupy.
• Pojedyncze słowo — przycisk „▶ Sprawdź teraz" na ekranie konkretnego słowa.

Sprawdzenie idzie w tle, nie blokuje przeglądarki. Możesz zamknąć kartę. Zakończenie zobaczysz w „Sprawdzenia" lub bezpośrednio w tabeli pozycji.

Status sprawdzenia

• ukończono — wszystkie słowa zaktualizowane.
• w toku — sprawdzenie trwa, lista odświeża się co 5 sekund.
• błąd — coś poszło nie tak (np. limit API). Treść błędu widoczna w tabeli.

5b. Ręczna korekta pomiaru ✏️

Czasem Google przemebluje wyniki w trakcie dnia, klient sprawdzi pozycję ze swojego komputera (z personalizacją) i dostaje inną liczbę niż w Twoim raporcie. Albo crawler trafi w moment przebudowy SERP-a i zwróci „brak", choć minutę wcześniej był TOP 3. Możesz wtedy ręcznie nadpisać konkretny pomiar.

Jak edytować pomiar

1. Wejdź w ekran konkretnego słowa (z listy słów, z kalendarza, z analizy).
2. W tabeli „Wszystkie pomiary" (na dole) znajdź wiersz z danym pomiarem (po dacie).
3. Kliknij „edytuj" po prawej stronie wiersza — rozwinie się formularz.
4. Wpisz właściwą pozycję dla każdego źródła (Organic / Wizytówki / Ads). Zostaw puste lub wpisz brak żeby usunąć pozycję.
5. W polu „Notatka" opisz dlaczego edytujesz (np. „klient sprawdził z Tyc, było TOP 3"). Zapisuje się przy pomiarze, widoczne w tabeli.
6. Kliknij Zapisz.

Co się dzieje po edycji

• Wiersz z edytowanym pomiarem jest oznaczony: ikona ✏️, podświetlone tło, treść notatki.
• System zapisuje kto i kiedy edytował (audyt). Jeśli pracujesz z klientem na publicznym linku, on widzi tylko końcową wartość bez Twojego nazwiska.
• Wartość trafia do wszystkich obliczeń — kalendarza, sparklin, analizy spadków/wzrostów, raportów, eksportu CSV. Tak jak każdy inny pomiar.
• Następne automatyczne sprawdzenie wpisze nowy wiersz — Twoja korekta zostaje na swojej dacie, nie znika.

6. Tabela kalendarzowa (pozycje per dzień)

Na ekranie strony, grupy lub słowa znajdziesz tabelę kalendarzową: wiersze to słowa, kolumny to dni miesiąca. Każda komórka pokazuje, na której pozycji byłeś tego dnia.

Co znaczą kolory komórki

• 3 — TOP 1–3 (świetnie, czołówka).
• 7 — TOP 4–10 (pierwsza strona Google).
• 22 — TOP 11–50 (do poprawy).
• 88 — dalej niż TOP 50.

Etykiety M-3 i A-1

Pojawiają się pod pozycją organic gdy w tym dniu jest też pomiar w Wizytówkach Google (M-N, np. M-3 = trzecia wizytówka w Mapach) lub w reklamach Ads (A-N, np. A-1 = pierwsza reklama). Liczba po myślniku to konkretna pozycja w tym źródle.

Najedź myszką na komórkę żeby zobaczyć tooltip z wszystkimi trzema pozycjami obok siebie (np. „Organic: 3 · Wizytówki: 1 · Ads: brak").

Filtry

• Od / Do — zakres dat (maks. 60 dni; jeśli przekroczysz, system automatycznie przytnie).
• Słowo zawiera — pokazuje tylko słowa zawierające wpisany ciąg.
• TOP od / TOP do — pokazuje tylko słowa, których pozycja w okresie mieści się w podanym przedziale (np. 1–10 = tylko te w pierwszej dziesiątce).

7. Zakładka „Analiza" — co się dzieje

Zakładka Analiza w górnym menu pokazuje, co się zmieniło w ostatnim okresie (domyślnie 7 dni). Cztery główne sekcje:

• 📈 Top wzrostów — słowa, które awansowały najwięcej miejsc.
• 📉 Top spadków — słowa, które straciły. Tu warto reagować najszybciej.
• 🌱 Świeżaki w TOP 10 — słowa, które dopiero co zaistniały (lub awansowały) w pierwszej dziesiątce.
• 👻 Wypadły poza TOP 100 — słowa, które teraz w ogóle nie pojawiają się w wynikach.
• ⚠️ Wypadły z TOP 10 — banner alertowy na górze: słowa, które jeszcze tydzień temu były w czołówce. To jest sygnał: trzeba sprawdzić co się stało.

Filtry: okres porównania (1, 3, 7, 14, 30, 90 dni) i klient (jeśli masz wielu, możesz zawęzić).

8. Raporty i eksporty

Raport okresowy

Z ekranu klienta lub z dashboardu kliknij „📄 Raport". Otrzymujesz stronę przygotowaną pod druk:

• Podsumowanie KPI (kafelki TOP).
• Wykres historii pozycji w okresie.
• Tabela wszystkich słów z kolumnami: aktualna pozycja, poprzednia (sprzed wybranego okresu), zmiana.

Eksport CSV

Każdy ekran (klient, strona, grupa, raport) ma przycisk ⤓ CSV — pobiera plik gotowy do otwarcia w Excelu polskim:

• Separator: średnik ;
• Kodowanie: UTF-8 z BOM (polskie znaki działają w Excelu)
• Kolumny: Słowo · Grupa · Strona · Pozycja organic · Pozycja Wizytówki · Pozycja Ads · Najlepsza · URL · Sprawdzono

PDF

Na stronie raportu kliknij „🖨 Drukuj / Zapisz PDF" — używa funkcji druku przeglądarki (Ctrl+P). Wybierasz drukarkę „Zapisz jako PDF" i dostajesz czysty plik.

9. Publiczne linki dla Twojego klienta

Każda grupa może mieć publiczny link, który możesz wysłać klientowi mailem. Klient klika, widzi swoje pozycje na żywo, bez logowania.

1. Wejdź w grupę.
2. W sekcji „🔗 Publiczny link do udostępnienia" kliknij „Wygeneruj publiczny link".
3. Pojawi się losowy adres URL — skopiuj i wyślij klientowi.

W dowolnej chwili możesz:

• Zresetować — wygenerować nowy URL (stary natychmiast przestaje działać).
• Wyłączyć — całkowicie zamknąć dostęp.

Strona publiczna ma znacznik noindex,nofollow — Google jej nie indeksuje, więc nie wycieknie do wyszukiwarek.

10. Limit miesięczny i prognoza zużycia

Każdy klient ma miesięczny limit zapytań (np. 5 000). Liczy się każde zapytanie do Google: 1 słowo × N sprawdzanych stron Google × ewentualne dodatki (Wizytówki, Ads).

Jak liczone są zapytania

• Organic (zawsze) = liczba sprawdzanych stron Google × 1. Np. 5 stron = 5 zapytań na słowo.
• Wizytówki (jeśli grupa ma „sprawdzaj Wizytówki") = +1 zapytanie na słowo.
• Ads (jeśli grupa ma „sprawdzaj Ads") = +mnożnik × liczba stron (zwykle 5–10×). To droższe API, dlatego mnożnik.

Prognoza w nagłówku

Obok licznika „X / Y zapytań" widzisz „prognoza: ~N/mies." — to szacunek, ile zapytań zużyjesz do końca miesiąca przy obecnych ustawieniach (liczba słów × częstotliwości × mnożniki).

Gdy prognoza przekracza limit, na górze pojawia się czerwony banner ostrzegawczy. Co zrobić:

• Zwolnij częstotliwość niektórych grup (np. z „co 1 dzień" na „co 3 dni").
• Wyłącz „Ads" w grupach gdzie nie jest niezbędny.
• Skontaktuj się z administratorem agencji o wyższy pakiet.

Przeniesienie niewykorzystanych kredytów (carryforward) ♻️

Jeśli administrator włączył Ci opcję „przenoszenie niewykorzystanych kredytów", to pod koniec miesiąca nieużyte kredyty (limit – zużycie) trafiają do Twojego banku. Dodają się do limitu w kolejnym miesiącu.

• Przykład: limit 5 000, zużyłeś 3 200 — 1 800 idzie do banku. Następny miesiąc: limit 5 000 + bank 1 800 = 6 800 dostępnych.
• Bank kumuluje się bez limitu — jak nie zużyjesz przez 3 miesiące, masz 3 × niewykorzystane.
• Bez tej opcji niewykorzystane przepadają 1. dnia miesiąca (klasyczny model).
• Stan banku widać w sekcji „limit" w profilu Twojego konta i w /api/v1/me (pole banked_credits).

Data wygaśnięcia konta ⏳

Administrator może ustawić datę wygaśnięcia Twojego konta (np. po opłaceniu okresu na 3 miesiące do przodu). Po tej dacie:

• Nie zalogujesz się — przy próbie pojawi się komunikat „Twoje konto wygasło. Skontaktuj się z administratorem".
• Cron nie uruchomi nowych sprawdzeń dla Twoich grup (oszczędność kredytów).
• Dane zostają — żaden pomiar, żadna grupa, żadne słowo nie znikają. Wystarczy że administrator przedłuży datę i wszystko wraca.

Konta bez ustawionej daty wygaśnięcia działają bezterminowo (domyślne).

11. Hurtowy import z CSV

Jeśli masz dużo słów, nie wpisuj ich pojedynczo — /import-csv.

Format pliku

grupa,slowo,kraj,miasto,strony,czestotliwosc
Glowne,plakatowanie,pl,,5,weekly
Lokalne Warszawa,plakatowanie warszawa,pl,Warszawa,3,weekly
Blog,jak rozwiesic plakat,pl,,5,monthly

• Wymagane kolumny: grupa, slowo. Reszta opcjonalna — jeśli pusta, używamy domyślnych z formularza powyżej.
• Separator: przecinek , lub średnik ; (system sam wykrywa).
• Częstotliwość: daily / weekly / monthly / manual lub po polsku codziennie / tygodniowo / miesięcznie / ręcznie.
• Grupy o tej samej nazwie są reużywane — kolejne słowa idą do tej samej grupy.

Możesz wkleić CSV jako tekst albo wgrać plik .csv. Pobierz przykładowy plik.

12. REST API — programowy dostęp

Pozycjosprawdzator ma pełny REST API v1 — możesz nim zarządzać klientami, stronami, grupami i słowami programowo. Idealne do:

• integracji z własnym systemem (CRM, raporty wewnętrzne)
• masowego dodawania klientów bez klikania w interfejsie
• cyklicznego uruchamiania sprawdzeń ze swojego cron-a (poza naszym)
• ściągania historii pozycji do własnego dashboardu
• obsługi przez agentów AI (np. Claude w CLI) — bot dodaje słowa, sprawdza, raportuje

12.1. Włączenie API (krok pierwszy)

API jest domyślnie wyłączone. Aby je aktywować i otrzymać swój token, napisz do nas:

📧 kontakt@pozycjosprawdzator.pl

W ciągu 24h odpiszemy z tokenem (długi losowy ciąg znaków, ok. 48 znaków). Po jego otrzymaniu możesz od razu wykonać pierwsze żądanie do API.

12.2. Pierwsze żądanie — sprawdzenie kto jestem

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

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

Odpowiedź:

{"id":3,"email":"klient@example.pl","role":"klient",
 "monthly_limit":5000,"used_this_month":1479,"remaining":3521}

12.3. Lista endpointów

12.4. Praktyczne przykłady

A) Dodać 50 słów do grupy jednym żądaniem

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

Odpowiedź zawiera inserted (lista nowych ID) i skipped (ile duplikatów pominęliśmy).

B) Pobrać historię pozycji jednego słowa

curl -H "X-API-Token: $TOKEN" \
  https://tutaj.pozycjosprawdzator.pl/api/v1/keywords/42/history

Zwraca tablicę pomiarów: data sprawdzenia, pozycja organic, pozycja w Wizytówkach, pozycja w Ads, znaleziony URL.

C) Uruchomić sprawdzenie grupy z własnego cron-a

# Plik /etc/cron.d/moj-cron:
0 3 * * 1 root curl -X POST -H "X-API-Token: $TOKEN" \
  https://tutaj.pozycjosprawdzator.pl/api/v1/check/group/5

Sprawdzi grupę 5 w każdy poniedziałek o 3:00. Zapytania liczą się do Twojego limitu miesięcznego (tak samo jak ręczne).

D) Zsynchronizować portfolio z własnym CRM (Python)

import os, requests

API = "https://tutaj.pozycjosprawdzator.pl/api/v1"
H = {"X-API-Token": os.environ["POSP_TOKEN"]}

# Lista klientów + ich strony + grupy
clients = requests.get(f"{API}/clients", headers=H).json()["items"]
for c in clients:
    sites = requests.get(f"{API}/sites?client_id={c['id']}", headers=H).json()["items"]
    for s in sites:
        groups = requests.get(f"{API}/groups?site_id={s['id']}", headers=H).json()["items"]
        print(f"{c['name']} / {s['domain']} → {len(groups)} grup")

E) Ręczna korekta pomiaru przez API

Tak samo jak w panelu (rozdz. 5b) — przydatne gdy klient zgłasza inną pozycję niż crawler znalazł, albo masz zewnętrzny weryfikator.

curl -X PUT https://tutaj.pozycjosprawdzator.pl/api/v1/rankings/12345 \
  -H "X-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organic_pos": 3, "maps_pos": 1, "ads_pos": null,
       "edit_note": "klient sprawdził z Tych, było TOP 3"}'

• Pole pominięte lub null = nie zmieniaj.
• Pole pusty string lub "brak" = ustaw pozycję na „brak w TOP".
• Pomiar zostaje oznaczony jako edytowany ręcznie (manually_edited=1), z Twoim user_id i czasem.
• Działa też dla pomiarów cudzych klientów tylko jeśli to Twoje konta — wymuszane na poziomie SQL.

F) Praca z Claude w CLI

Możesz dać Claude'owi token API i poprosić: „Dodaj klienta XYZ ze stroną xyz.pl, grupą Główne i słowami z tej listy. Potem uruchom sprawdzenie i pokaż mi wyniki." Claude wykona to przez kilka żądań do API.

12.5. Kody odpowiedzi

• 200 — OK, w ciele JSON z danymi.
• 201 — Utworzono (po POST nowego zasobu).
• 400 — Błąd wejścia (brakujące pole, zła wartość). W ciele {"detail":"..."}.
• 401 — Brak / nieprawidłowy token. Sprawdź nagłówek X-API-Token.
• 403 — Nie masz dostępu do tego zasobu (np. próbujesz pobrać klienta innego użytkownika).
• 404 — Zasób nie istnieje (lub został usunięty).

12.6. Limity i dobre praktyki

• Każde uruchomione sprawdzenie liczy się do Twojego miesięcznego limitu zapytań — tak samo jak w panelu.
• API jest multi-tenant: widzisz tylko swoich klientów. Próba dostępu do cudzego = 403.
• POST/PUT/DELETE wymagają nagłówka Content-Type: application/json.
• Sprawdzenia są asynchroniczne — POST do /check/... zwraca natychmiast „started", a sprawdzenie idzie w tle. Status sprawdzaj przez GET /api/v1/runs.
• Jeśli zaczniesz robić tysiące żądań na minutę — zwolnij. Na razie nie ma sztywnego rate-limitu, ale zachowaj zdrowy rozsądek (1 zapytanie / sekundę = OK).

13. FAQ — częste pytania

14. Kontakt

Coś nie działa? Coś niejasne? Masz pomysł na funkcję?

📧 kontakt@pozycjosprawdzator.pl

Odpowiadamy w ciągu 24 godzin (w dni robocze).