SilentShield

Koncové body widgetu

Tieto koncové body volá widget SilentShield. Zvyčajne ich nevoláte sami — sú zdokumentované, aby ste mohli sledovať, čo sa na vašej stránke deje.

Base URL: https://api.silentshield.io

POST/api/v1/telemetry/behavior

Odošle údaje o správaní pri aktuálnej interakcii (myš, klávesnica, posúvanie) a vráti nonce spolu s verdiktom. Váš formulár tento nonce odošle ako pole `behavior_nonce`.

Auth: API kľúč (hlavička X-Api-Key)

Request Body:

{"ts": 1767225600000, "nonce": "bh_abc123", "event": "submit", "form_key": "contact", "feature_hash": "...", "metrics": {...}, "signature": "..."}

Response:

{"id": "...", "nonce": "bh_abc123", "status": "queued", "verdict": "human", "score": 0.87, "captcha_solved": false, "challenge_required": false, "difficulty": "pass", "reason_codes": [], "action": "allow"}

Započítava sa do vašej kvóty, len čo príde udalosť `submit` s nonce — presne raz na odoslanie. `init`, `telemetry` a `form_detected` sa nezapočítavajú.

POST/api/v1/captcha/challenge

Vyžiada si počtovú úlohu, keď bol verdikt neistý. Widget to urobí sám; úloha je jednorazová a viazaná na nonce.

Auth: API kľúč (hlavička X-Api-Key)

Request Body:

{"nonce": "bh_abc123", "difficulty": "medium"}

Response:

{"ok": true, "challenge_id": "ch_xyz789", "a": 7, "op": "+", "b": 5}

Potrebné len vtedy, keď odpoveď telemetrie ohlásila `challenge_required: true`.

POST/api/v1/captcha/verified

Odošle vyriešenú úlohu. Nonce sa označí ako ľudský až vtedy, keď odpoveď zodpovedá úlohe, ktorú server vydal pre tento kľúč.

Auth: API kľúč (hlavička X-Api-Key)

Request Body:

{"challenge_id": "ch_xyz789", "answer": 12}

Response:

{"ok": true}   //  403: {"ok": false, "reason": "invalid_solution"}

Fail-closed: nesprávna alebo vypršaná odpoveď vráti 403 s `reason: "invalid_solution"`. Úloha je jednorazová.

POST/api/v1/captcha/verify-nonce

Overí nonce vygenerovaný widgetom. Zavolajte toto zo svojho servera na potvrdenie, že odoslanie formulára je legitímne.

Auth: API kľúč (hlavička X-Api-Key)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

{"valid": true, "verdict": "human", "score": 0.92, "timestamp": "2025-01-15T10:30:00Z"}

Tento koncový bod sa počíta do kvóty. Nonce sú jednorazové a vypršia po 5 minútach.