DLA INTEGRACJI
Dokumentacja API
Zarządzaj kampaniami i odczytuj wyniki z własnego programu.
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
| Pole | Typ / wartości | Znaczenie |
|---|---|---|
name | tekst, wymagane | Nazwa kampanii. |
urls | tekst, wymagane | Pełne adresy http/https, jeden w linii. Powtórzenia w żądaniu są pomijane. |
indexing_enabled | 0 lub 1 | Włącz zgłoszenia do indeksowania. |
monitoring_enabled | 0 lub 1 | Włącz sprawdzanie indeksacji. Co najmniej jeden moduł musi być włączony. |
indexing_mode | immediate / dripfeed | Domyślnie immediate. Dripfeed rozkłada zgłoszenia na dni. |
indexing_start_at | data i godzina | Domyślnie teraz. Zalecany format: YYYY-MM-DD HH:MM:SS, w strefie czasu serwisu. |
indexing_daily_limit | liczba ≥ 1 | Limit URL na dzień dla dripfeed; domyślnie 100. |
monitor_provider | system / desktop_gsc | Domyślnie system. desktop_gsc wymaga udostępnionego programu Windows; obecnie program jest w przygotowaniu. |
monitor_mode | once / interval / until_indexed | Przy włączonym monitoringu domyślnie once. |
monitor_first_delay_days | liczba ≥ 0 | Dni do pierwszej kontroli; domyślnie 7. |
monitor_interval_days | liczba ≥ 1 | Odstęp kolejnych kontroli; domyślnie 7. |
monitor_max_checks | liczba ≥ 0 | Limit kontroli jednego URL. 0 oznacza brak limitu liczbowego. |
monitor_end_at | data i godzina / puste | Opcjonalny termin końcowy. |
stop_monitoring_when_indexed | 0 lub 1 | Zakończ monitoring po potwierdzeniu indeksacji. |
auto_resubmit | 0 lub 1 | Ponawiaj zgłoszenie po negatywnych kontrolach. Wymaga obu modułów. |
resubmit_after_failed_checks | liczba ≥ 1 | Liczba negatywnych kontroli przed ponownym zgłoszeniem; domyślnie 2. |
max_resubmits | liczba ≥ 0 | Maksymalna liczba ponownych zgłoszeń na URL; 0 wyłącza ponowienia. |
Dla kampanii monitoringu ustaw monitoring_enabled=1 i monitor_provider=system. Kontrole cykliczne: monitor_mode=interval oraz monitor_interval_days. Miesięczna częstotliwość kalendarzowa i edycja monitoringu są obecnie dostępne w panelu, bez osobnego endpointu edycji.
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.
| Pole | Typowe wartości |
|---|---|
| submit_status | disabled, scheduled, submitted |
| index_status | unknown, indexed, not_indexed |
| monitoring_status | disabled, 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
- 401: missing_api_key lub invalid_api_key — brak, unieważniony klucz albo nieaktywne konto.
- 400: niepoprawne dane lub za mało punktów przy tworzeniu kampanii; opis w error.
- 404: not_found / campaign_not_found / job_not_found — zasób nie istnieje lub nie należy do konta.
- 405: method_not_allowed — użyj POST w endpointach, które tego wymagają.
- 409: campaign_archived lub job_not_claimed — konflikt bieżącego stanu.
- 403: invalid_claim_token — niewłaściwy token odebranego zadania.
- 422: invalid_status — niedozwolony status wyniku zadania.
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.