HamCaptcha
Zjišťuji stav služby…

Služba pro CAPTCHA výzvy s radioamatérskými volačkami

HamCaptcha chrání formuláře registrovaných projektů: do stránky se vloží widget s veřejným projectKey, uživatel opíše radioamatérskou volačku — reálnou značku účastníka závodu CQWW SSB 2025 — z PNG obrázku a widget získá jednorázový token. Backend projektu pak token ověří tajným secret na endpointu /v2/verify. Tokeny platí 300 sekund a lze je validovat jen jednou.

Dokumentace a rozhraní

Jak výzva probíhá

Widget ve stránce

Stránka načte skript /v2/api.js a vloží <div class="hamcaptcha" data-projectkey="…">. Widget si sám stáhne obrázek s volačkou a zobrazí ho s textovým polem.

Token po opsání

Uživatel volačku opíše; při správné odpovědi widget získá jednorázový token, vloží ho do formuláře jako hidden input hamcaptcha-token a zavolá data-on-success.

Server-side validace

Backend projektu odešle token se svým tajným klíčem na POST /v2/verify a podle success: true/false požadavek přijme, nebo odmítne.

Základní parametry

Klientská část Skript /v2/api.js + <div class="hamcaptcha">; widget volá POST /v2/challenge a POST /v2/answer s veřejným projectKey
Server-side validace POST /v2/verify s tajným secret v těle requestu (JSON i form-urlencoded)
Klíče projektu Pár projectKey (veřejný) + secret (tajný) přidělí správce služby při registraci projektu
Tokeny Platnost 300 sekund, validace jen jednou (token-already-used); bezpečné opakování přes idempotency_key
Formát obrázku PNG jako data URL — text výzvy není v odpovědi čitelný jinak než z obrázku
Rate limity Výchozí 60 výzev + 60 validací za minutu na projekt; překročení vrací 429
Uchovávání dat Výzvy a tokeny žijí jen v paměti služby po dobu platnosti; nic se neukládá, provozní události se pouze protokolují

Ukázka použití

1) Widget ve stránce — HTML
<script src="https://<hamcaptcha>/v2/api.js" async defer></script>

<form method="post" action="/registrace">
  …
  <div class="hamcaptcha" data-projectkey="<PROJECT_KEY>"></div>
  <button>Odeslat</button>
</form>

→ po opsání volačky widget vloží token do hidden inputu "hamcaptcha-token"
2) Server-side validace tokenu — curl
curl -X POST /v2/verify \
  -H 'Content-Type: application/json' \
  -d '{"secret": "<SECRET>", "token": "<token-z-formuláře>"}'

→ {"success": true, "solved_at": "2026-06-11T15:14:30Z", "hostname": "klient.cz", "errors": []}
3) Server-side ověření — Java (Spring)
// token přijde ve formuláři jako pole "hamcaptcha-token"
record VerifyRequest(String secret, String token) {}
record VerifyResponse(boolean success, List<String> errors) {}

VerifyResponse v = restClient.post()
        .uri("https://<hamcaptcha>/v2/verify")
        .body(new VerifyRequest(secret, captchaToken))   // secret z konfigurace
        .retrieve()
        .body(VerifyResponse.class);

if (v == null || !v.success()) {
    // NOK → nechat uživatele vyřešit novou captchu
}
// OK → pokračovat ve zpracování formuláře
4) Server-side ověření — PHP
// token přijde ve formuláři jako pole "hamcaptcha-token"
$ch = curl_init('https://<hamcaptcha>/v2/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'secret' => getenv('HAMCAPTCHA_SECRET'),   // secret z konfigurace
        'token'  => $_POST['hamcaptcha-token'] ?? '',
    ]),
]);
$result = json_decode(curl_exec($ch), true);

if (empty($result['success'])) {
    // NOK → nechat uživatele vyřešit novou captchu
}
// OK → pokračovat ve zpracování formuláře

Kompletní návod krok za krokem s živou ukázkou najdete na stránce ukázkové integrace; úplný popis polí a chybových kódů v dokumentaci API.

Živá ukázka

Skutečný widget této instance (skript /v2/api.js). Zadejte veřejný projectKey registrovaného projektu — po správném opsání volačky widget získá token a níže se vypíše hotový curl příkaz pro server-side validaci. Tajný secret do prohlížeče nepatří, validaci provádí vždy backend projektu.