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"}

실패 시 차단: 틀렸거나 만료된 답은 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분 후에 만료됩니다.