Publiczne API: klucze, uprawnienia i scenariusze
Publiczne API pozwala zarządzać promocją z własnego systemu: tworzyć projekty, dodawać strony, uruchamiać kaskady, uzyskiwać raporty, a także pracować z kontrolą pozycji, audytami i skanami bezpieczeństwa.
Dokumentacja
Pełny podręcznik z parametrami i przykładami zapytań znajduje się na oddzielnej stronie i zawsze odpowiada bieżącej wersji. Tutaj — tylko ogólny obraz.
Klucze i uprawnienia
- Klucz wydawany jest w panelu, w sekcji „API dla deweloperów”, i przekazywany w nagłówku autoryzacji.
- Klucz ma zakresy — zestawy uprawnień. Jest ich cztery: promocja (promotion), pozycje (rank), audyty (audit), bezpieczeństwo (shield). Wydawaj tylko to, co naprawdę potrzebne.
- Klucz można cofnąć w każdej chwili, stare zapytania z nim natychmiast przestaną działać.
- Obowiązuje ograniczenie częstotliwości zapytań; w panelu widoczna jest statystyka wywołań i wydatków związanych z kluczem.
Co jest dostępne przez API
| Grupa | Możliwości | Zakres |
|---|---|---|
| Konto | Profil, saldo, osobisty rabat, informacje o kluczu | nie wymagane |
| Projekty i linki | Tworzenie projektów, dodawanie i usuwanie stron | promotion |
| Promocja | Taryfy, wstępne obliczenia, uruchamianie kaskady, status i lista publikacji | promotion |
| Raporty i marka | Raport w JSON lub PDF, ustawienia white-label (tylko Pro) | promotion |
| Rank Tracker | Projekty, słowa kluczowe, ustawienie kontroli pozycji | rank |
| SEO Audit | Ocena rozmiaru strony, ekspresowe i pełne skanowanie, wyniki z Health Score | audit |
| Shield | Potwierdzenie domeny, uruchamianie skanów, werdykt | shield |
Brandowanie raportów — nie jest oddzielnym zakresem: wchodzi w skład promocji i wymaga aktywnej subskrypcji Pro.
Typowy scenariusz
- Utworzyć projekt i dodać do niego strony.
- Poprosić o obliczenie kosztów dla potrzebnej konfiguracji kaskady.
- Uruchomić promocję i zapisać identyfikator uruchomienia.
- Okresowo pytać o status, a po zakończeniu — raport z publikacjami.
Wstępne obliczenie zwraca kwotę ze zniżką i bieżące saldo, dlatego cenę można pokazać przed pobraniem; jak jest ustalona — w artykule taryfy i cena. Raport zwraca tylko potwierdzone publikacje, jak w panelu: wartości statusów omówione są w artykule raport i statusy.
Limity i kody odpowiedzi
| Sytuacja | Odpowiedź | Co robić |
|---|---|---|
| Klucz nie został przekazany, nie znaleziono go lub został cofnięty | 401 | Sprawdzić nagłówek autoryzacji i sam klucz |
| Klucz nie ma potrzebnego zakresu | 403 | Wydać klucz z potrzebnymi uprawnieniami |
| Brak środków na uruchomienie | 402 | W odpowiedzi przyjdzie wymagana kwota, saldo, niedobór i link do doładowania |
| Błąd w parametrach lub obca domena linku | 422 | Pole z błędem jest wskazane w odpowiedzi |
| Zbyt wiele zapytań | 429 | Powtórzyć po liczbie sekund z odpowiedzi; limit jest liczony na klucz |
| Usługa tymczasowo wyłączona | 503 | Powtórzyć później: uruchomienie się nie odbyło, pieniądze nie zostały pobrane |
Listy są zwracane strona po stronie — nie więcej niż 100 elementów na stronę. Pełna lista kodów znajduje się w podręczniku.
Częste błędy integracji
- Ponowne uruchomienie tego samego linku. Dopóki trwa aktywna kaskada, nowa nie jest tworzona — w odpowiedzi przyjdzie oznaczenie „już aktywny”. To nie jest błąd, nie ma potrzeby powtarzania zapytania w cyklu.
- Pełny audyt bez ekspresu, skan Shield bez potwierdzenia domeny. Oba działania wymagają kroku przygotowawczego, w przeciwnym razie zwróci błąd.
- Zbyt częste pytanie o status. Kaskada trwa godzinami: pytanie częściej niż co kilka minut nie ma sensu, a łatwo można natrafić na limit częstotliwości.
- Puste saldo w momencie uruchomienia. Wstępne obliczenie mogło odbyć się wczoraj, a pieniądze mogły pójść na inne uruchomienia — miej zapas, zob. saldo i doładowanie.
White-label przez API
Subskrybenci Pro mogą ustawić logo, nazwę firmy i kolor — wtedy raporty uzyskane przez API będą dostosowane do Twojej marki. Więcej w artykule o White-label.
Serwer przechowuje tylko hash klucza, ponowne pokazanie wydanego klucza nie jest możliwe — zachowaj go od razu. Zgubiłeś lub ujawniłeś w repozytorium: cofnij stary i wydaj nowy, na już uruchomione kaskady to nie wpływa.