SilentShield

Крайни точки на уиджета

Тези крайни точки се извикват от уиджета на SilentShield. Обикновено не ги извиквате сами — документирани са, за да проследите какво се случва на страницата ви.

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

POST/api/v1/telemetry/behavior

Изпраща поведенческите данни от текущото взаимодействие (мишка, клавиатура, скролиране) и връща nonce заедно с оценка. Формулярът ви изпраща този nonce като поле `behavior_nonce`.

Auth: API ключ (заглавка 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"}

Отчита се към квотата ви веднага щом събитието `submit` пристигне с nonce — точно веднъж на изпращане. `init`, `telemetry` и `form_detected` не се отчитат.

POST/api/v1/captcha/challenge

Заявява аритметична задача, когато оценката е несигурна. Уиджетът прави това сам; задачата е еднократна и обвързана с nonce.

Auth: API ключ (заглавка X-Api-Key)

Request Body:

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

Response:

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

Нужно е само когато отговорът на телеметрията е съобщил `challenge_required: true`.

POST/api/v1/captcha/verified

Изпраща решената задача. Nonce се маркира като човешки само когато отговорът съвпада със задача, издадена от сървъра за този ключ.

Auth: API ключ (заглавка X-Api-Key)

Request Body:

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

Response:

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

Fail-closed: грешен или изтекъл отговор връща 403 с `reason: "invalid_solution"`. Задачата е еднократна.

POST/api/v1/captcha/verify-nonce

Верифицира nonce, генериран от уиджета. Извикайте това от сървъра си, за да потвърдите, че изпращането на формуляра е легитимно.

Auth: API ключ (заглавка X-Api-Key)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

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

Тази крайна точка се брои към квотата ви. Nonce стойностите са за еднократна употреба и изтичат след 5 минути.