API Wzywam.pl (v1)
Publiczne API tylko do odczytu. Adres bazowy: /api/v1. Odpowiedzi w JSON (UTF-8). Wersja v1 jest stabilna; zmiany łamiące pojawią się jako v2.
Uwierzytelnianie
Token tworzysz w ustawieniach konta (/konto/api) — pokazujemy go tylko raz. Wysyłaj go w nagłówku:
Authorization: Bearer wz_…
Bez tokenu dostępne są dane publiczne (60 żądań/min na adres IP). Z tokenem: 120 żądań/min na token oraz dostęp do wyzwań prywatnych, do których masz dostęp w serwisie.
Końcówki
| Metoda | Adres | Opis |
|---|---|---|
| GET | /api/v1/challenges?category=1&state=active&cursor=… |
publiczne wyzwania, stronicowanie kursorem (next_cursor) |
| GET | /api/v1/challenges/{tag} |
jedno wyzwanie |
| GET | /api/v1/challenges/{tag}/nominations?cursor=… |
zaakceptowane nominacje |
| GET | /api/v1/challenges/{tag}/stats |
liczby: nominacje, głębokość, K, kliknięcia, konwersja, źródła, dziennie |
| GET | /api/v1/me |
właściciel tokenu, jego organizacje i wyzwania (token wymagany) |
| GET | /api/verify/{handle} |
profil zweryfikowany twórcy (bez tokenu) |
Kody: 401 brak lub nieważny token, 403 brak dostępu, 404 nie ma, 429 limit.
Webhooki (organizacje z planem Business/Teams)
Rejestracja w panelu organizacji: adres https:// (bez adresów IP i sieci prywatnych) i lista zdarzeń: nomination.accepted, challenge.published, challenge.expired, winners.published, battle.finished. Sekret pokazujemy raz.
Każde dostarczenie to POST z JSON { "id", "event", "created_at", "data" } i nagłówkami X-Wzywam-Event, X-Wzywam-Delivery oraz X-Wzywam-Signature: t=<unix>,v1=<hex>, gdzie v1 = HMAC-SHA256(secret, t + "." + body). Odrzuć żądania z podpisem starszym niż 5 minut. Odpowiedz kodem 2xx w ciągu 5 s; przy błędzie ponawiamy 5 razy (1 min → 2 h). Po 20 nieudanych dostarczeniach z rzędu webhook jest wyłączany.
Przykład weryfikacji (PHP):
[$t, $v1] = explode(',', $header); $t = substr($t, 2); $v1 = substr($v1, 3);
$ok = hash_equals(hash_hmac('sha256', $t.'.'.$body, $secret), $v1) && abs(time() - (int) $t) < 300;