Partner API — Quickstart
Integracja Selpio jako data provider w Twojej aplikacji. Analizuj strony swoich klientów końcowych przez nasze API, bez logowania ich do Selpio.
Zanim zaczniesz
Kiedy Partner API? Gdy budujesz własny produkt (SaaS, dashboard agencji, plugin) i potrzebujesz danych AI-readiness dla swoich klientów. Rozliczenie z Selpio per usage — Twoi klienci nie wiedzą o nas.
Gdy tego NIE chcesz: jeśli po prostu potrzebujesz audytu jednej strony → użyj planu Monthly/Agency i analizuj przez dashboard.
Krok 1 — Rejestracja i trial
- Zaloguj się na konto Selpio (lub załóż nowe na selpio.com)
- Wejdź na
/dashboard/partner/signup - Kliknij Rozpocznij trial — dostajesz klucz API natychmiast
Trial: 10 darmowych crawlów, ważność 30 dni, bez karty płatniczej.
⚠️ Klucz API pokazujemy TYLKO RAZ — zapisz go od razu w menedżerze sekretów albo zmiennej środowiskowej. Jeśli zgubisz, musisz wygenerować nowy (stary przestaje działać).
Krok 2 — Pierwszy crawl
curl -X POST https://api.selpio.com/api/v1/partner/crawls \
-H "Authorization: Bearer sk_live_TWOJ_KLUCZ" \
-H "Content-Type: application/json" \
-d '{
"domain": "https://klient.com",
"externalClientRef": "customer_abc",
"maxPages": 30
}'Odpowiedź (202 Accepted):
{
"success": true,
"data": {
"id": "7f8a9b2c-...",
"domain": "https://klient.com/",
"status": "queued",
"externalClientRef": "customer_abc"
}
}Pola wymagane
| Pole | Opis |
|---|---|
domain | Adres startowy crawla (HTTPS/HTTP). Nie może wskazywać na private IP / localhost |
externalClientRef | Wymagane. Twój identyfikator klienta końcowego. Format: alphanumerics + _ -, 1-100 znaków, bez PII (nie email, nie imię). |
Pola opcjonalne
| Pole | Default | Opis |
|---|---|---|
maxPages | 30 | Limit stron w crawlu. Bez “page unlock” max 30, z unlock (+30 zł/mc) max 100. |
Krok 3 — Status crawla
curl https://api.selpio.com/api/v1/partner/crawls/7f8a9b2c-... \
-H "Authorization: Bearer sk_live_TWOJ_KLUCZ"Status leci: queued → running → completed (lub failed). Typowy czas: 3-10 minut dla 30 stron.
Po completed response zawiera report — pełny JSON z score, dimensions (structure/semantics/schema/llm_access/seo), topIssues (max 10 krytycznych problemów), pages (per-page scores).
Krok 4 — Odbieraj wyniki przez webhook (zalecane)
Polling co N sekund jest dopuszczalny, ale webhook jest tańszy i szybszy — dostajesz POST gdy tylko crawl się skończy.
Skonfiguruj webhook URL w dashboardzie → Settings → “Webhook URL”. Dostaniesz nowy secret — zapisz go.
Selpio wyśle POST na Twój URL:
{
"event": "crawl.completed",
"crawl_id": "7f8a9b2c-...",
"external_client_ref": "customer_abc",
"status": "completed",
"score": 78,
"finished_at": "2026-04-20T14:30:00Z"
}W headerze X-Selpio-Signature: sha256=<hex> — weryfikuj HMAC żeby mieć pewność że POST pochodzi od Selpio. Szczegóły w Partner API — Webhooks.
Lista crawlów
curl https://api.selpio.com/api/v1/partner/crawls?page=1&limit=20 \
-H "Authorization: Bearer sk_live_TWOJ_KLUCZ"Kody błędów
| Kod HTTP | error.code | Znaczenie |
|---|---|---|
| 401 | MISSING_API_KEY | Brak headera Authorization: Bearer |
| 401 | INVALID_API_KEY | Klucz nieprawidłowy lub unieważniony |
| 403 | WRONG_TIER_ENDPOINT | Używasz klucza Agency na endpoincie /partner/* |
| 403 | TRIAL_EXHAUSTED | Wykorzystałeś 10/10 trial crawlów |
| 403 | TRIAL_EXPIRED | Trial wygasł po 30 dniach |
| 403 | APPROVAL_PENDING | Aplikacja w weryfikacji (1-3 dni roboczych) |
| 400 | MISSING_CLIENT_REF | Brak externalClientRef w body |
| 400 | PAGE_LIMIT_EXCEEDED | maxPages > 30 bez unlocka |
| 429 | Throttled | Rate limit (60 req/min per klucz) |
Billing — dwa modele
Po trial przejdź na pełny plan przez formularz aplikacji (NIP/VAT). Wybierz jeden z modeli w dashboardzie:
Model A — per crawl (prostszy)
- 299 zł/mc minimum (zawiera 20 crawlów)
- +15 zł za każdy crawl ponad 20
- Dobre dla: małego wolumenu, niepewnej liczby klientów
Model B — per unique client
- 299 zł/mc minimum (zawiera 10 unikalnych klientów × 20 crawlów)
- +30 zł za każdego dodatkowego unikalnego
externalClientRef - +15 zł za każdy crawl ponad 20/klient/mc
- Dobre dla: stałej bazy klientów robiących wiele crawlów
Uwaga: zmiana modelu możliwa raz na 30 dni, aplikuje się od następnego cyklu billingowego. Forecast obu modeli widoczny w dashboardzie.
Page unlock
Za +30 zł/mc flat zwiększasz limit z 30 do 100 stron/crawl. Włącz w dashboardzie → Settings.
FAQ
Czy mogę mieć wiele kluczy API? Nie. Jeden klucz per konto. Rotacja: wygenerowanie nowego klucza unieważnia stary natychmiast.
Czy klient końcowy loguje się do Selpio? Nie. Partner API to pure data layer. Ty pokazujesz dane w swoim UI, klient końcowy nie ma relacji z Selpio.
Czy dostaję PDF z raportem? Nie — tylko JSON. PDF generujesz sam po swojej stronie z danych JSON.
Co się dzieje po 6 nieudanych webhook delivery?
Partner dostaje email webhook_failed z opisem błędu. Zaktualizuj URL w dashboardzie, kolejne crawle dostaną nowy webhook (ten konkretny job zostaje w failed — nie wysyłamy go ponownie).