Index Monitor

DLA INTEGRACJI

Dokumentacja API

Zarządzaj kampaniami i odczytuj wyniki z własnego programu.

Utwórz klucz APIPobierz OpenAPI / Postman

1. Połączenie i autoryzacja

Adres bazowy: https://index.i4a.pl/api/. Utwórz klucz w Profilu. Pełna wartość jest widoczna tylko po utworzeniu; w przykładach zastąp TWOJ_KLUCZ_API własnym kluczem.

Każde żądanie wymaga nagłówka Authorization: Bearer TWOJ_KLUCZ_API. Obsługiwany jest też nagłówek X-API-Key: TWOJ_KLUCZ_API. Klucz daje dostęp do danych jego właściciela — nie umieszczaj go w publicznym JavaScript strony.

POST przyjmuje JSON z Content-Type: application/json lub zwykłe pola formularza. Odpowiedzi mają format {"ok":true,"data":...} albo {"ok":false,"error":"..."}. Poniższe przykłady curl są zapisane dla powłoki Bash; OpenAPI można zaimportować do Postmana i innych klientów HTTP.

curl "https://index.i4a.pl/api/account.php" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API"

Odpowiedź konta

{"ok":true,"data":{"user_id":123,"email":"konto@example.com","credits":1000}}

credits oznacza dostępne punkty ze wszystkich aktywnych i niewygasłych pul, po odjęciu rezerwacji.

2. Utwórz kampanię

POST campaign_create.php. Minimalny przykład kampanii indeksowania:

curl -X POST "https://index.i4a.pl/api/campaign_create.php" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{"name":"Moja kampania","indexing_enabled":1,"urls":"https://example.com/strona-1\nhttps://example.com/strona-2"}'
{"ok":true,"data":{"campaign_id":42,"urls":2,"invalid":0,"duplicates":0,"estimated_max_cost":20}}

ID w odpowiedzi wykorzystasz w kolejnych żądaniach. estimated_max_cost jest prognozą dla wybranych ustawień; faktyczne ceny pochodzą z aktualnego cennika. Nie zakładaj stałej ceny z powyższego przykładu.

Warunek finansowania: zapis wymaga punktów na zgłoszenia i pierwsze sprawdzenia wszystkich adresów. Środki są rezerwowane w tej samej transakcji co zapis kampanii. Brak środków odrzuca całą kampanię, bez utworzenia części URL-i. Dla zaplanowanych zadań uwzględniamy ważność puli punktów. Następne cykle oraz ponowne zgłoszenia wymagają dalszych punktów.

Nie ponawiaj automatycznie utworzenia kampanii po timeoutcie: ten endpoint nie obsługuje klucza idempotencji. Sprawdź w panelu, czy kampania została zapisana.

Wszystkie ustawienia tworzenia kampanii
PoleTyp / wartościZnaczenie
nametekst, wymaganeNazwa kampanii.
urlstekst, wymaganePełne adresy http/https, jeden w linii. Powtórzenia w żądaniu są pomijane.
indexing_enabled0 lub 1Włącz zgłoszenia do indeksowania.
monitoring_enabled0 lub 1Włącz sprawdzanie indeksacji. Co najmniej jeden moduł musi być włączony.
indexing_modeimmediate / dripfeedDomyślnie immediate. Dripfeed rozkłada zgłoszenia na dni.
indexing_start_atdata i godzinaDomyślnie teraz. Zalecany format: YYYY-MM-DD HH:MM:SS, w strefie czasu serwisu.
indexing_daily_limitliczba ≥ 1Limit URL na dzień dla dripfeed; domyślnie 100.
monitor_providersystem / desktop_gscDomyślnie system. desktop_gsc wymaga udostępnionego programu Windows; obecnie program jest w przygotowaniu.
monitor_modeonce / interval / until_indexedPrzy włączonym monitoringu domyślnie once.
monitor_first_delay_daysliczba ≥ 0Dni do pierwszej kontroli; domyślnie 7.
monitor_interval_daysliczba ≥ 1Odstęp kolejnych kontroli; domyślnie 7.
monitor_max_checksliczba ≥ 0Limit kontroli jednego URL. 0 oznacza brak limitu liczbowego.
monitor_end_atdata i godzina / pusteOpcjonalny termin końcowy.
stop_monitoring_when_indexed0 lub 1Zakończ monitoring po potwierdzeniu indeksacji.
auto_resubmit0 lub 1Ponawiaj zgłoszenie po negatywnych kontrolach. Wymaga obu modułów.
resubmit_after_failed_checksliczba ≥ 1Liczba negatywnych kontroli przed ponownym zgłoszeniem; domyślnie 2.
max_resubmitsliczba ≥ 0Maksymalna liczba ponownych zgłoszeń na URL; 0 wyłącza ponowienia.

3. Odczytaj stan kampanii

GET campaign_status.php?id=42. Zwraca obiekt data.campaign z ustawieniami, licznikami i stanem zapisanym w bazie oraz data.groups z liczbą URL-i dla kombinacji stanów:

curl "https://index.i4a.pl/api/campaign_status.php?id=42" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API"
{"ok":true,"data":{"campaign":{"id":42,"name":"Moja kampania","status":"active"},"groups":[{"submit_status":"submitted","index_status":"indexed","monitoring_status":"finished","cnt":2}]}}

Powyżej skrócono obiekt kampanii. campaign.status opisuje włączenie pracy (active / paused), a archived_at archiwum. Zakończenie działań oceniaj również na podstawie stanów URL-i i ustawień monitoringu; sam status active nie oznacza trwającej wysyłki.

PoleTypowe wartości
submit_statusdisabled, scheduled, submitted
index_statusunknown, indexed, not_indexed
monitoring_statusdisabled, scheduled, checked, finished

4. Dodaj adresy do kampanii

POST urls_add.php. Pola: campaign_id i urls (jeden URL w linii).

curl -X POST "https://index.i4a.pl/api/urls_add.php" \
  -H "Authorization: Bearer TWOJ_KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":42,"urls":"https://example.com/strona-3"}'
{"ok":true,"data":{"added":1,"funding_rejected":0,"invalid":0,"duplicates_in_input":0}}

Adresy są dodawane i finansowane pojedynczo. Wynik może być częściowy: sprawdzaj added oraz funding_rejected. Istniejący URL w tej kampanii jest pomijany, bez kolejnej opłaty. duplicates_in_input dotyczy powtórzeń w samym żądaniu. Nowe adresy dziedziczą aktualne ustawienia kampanii; kampania zarchiwizowana nie przyjmuje nowych URL-i.

5. Program Windows i własne klienty GSC

Program Windows jest w przygotowaniu. Nowy wybór desktop_gsc pozostaje zablokowany do jego udostępnienia. Poniższe endpointy opisują protokół klienta i obsługują już istniejące zadania desktopowe.

GET jobs_fetch.php?limit=20 — pobiera i przypisuje do klucza do 100 gotowych zadań desktop_gsc / mixed; domyślnie 20. To nie jest podgląd: odbiór rezerwuje punkty, oznacza zadanie jako processing i zwraca jednorazowy claim_token. Zadania systemowe wykonuje serwer.

{"ok":true,"data":{"jobs":[{"id":7,"type":"check","campaign_id":42,"campaign_url_id":99,"scheduled_at":"2026-10-31 10:00:00","attempt":1,"claim_token":"TOKEN_Z_ODPOWIEDZI","payload":{"url":"https://example.com/strona-3"}}]}}

POST jobs_result.php — zwraca wynik zadania pobranego tym samym kluczem. Wymagane: job_id, claim_token, status. Dla check użyj indexed, not_indexed albo error. Dla submit / resubmit: submitted albo error. Opcjonalnie: message, a dla błędu error.

{"job_id":7,"claim_token":"TOKEN_Z_ODPOWIEDZI","status":"indexed"}

Nie wysyłaj wyniku na podstawie samego ID zadania ani nie odczytuj zadań kluczem innego konta. Powtórny wynik zakończonego zadania zwróci HTTP 409; nie ponawiaj płatnej operacji tylko z powodu tego kodu.

6. Błędy i ograniczenia

Obecne API nie udostępnia listowania wszystkich kampanii, edycji monitoringu, płatności ani archiwizacji. Te działania wykonasz w panelu. Zgłoszenie URL nie gwarantuje jego indeksacji.