API-Referenz

CaptchaLa stellt eine RESTful API für alle serverseitigen Integrationen bereit.

Basis-URL

https://apiv1.captcha.la

Authentifizierung

Alle API-Anfragen erfordern Authentifizierungs-Header:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret ist ausschließlich serverseitig. Geben Sie es niemals an Browser, mobile Apps oder öffentliche Repositories weiter.

Serverseitige Validierungs-API

💡 Verwenden Sie ein Server-SDK, um sich den Boilerplate-Code zu sparen. Es kapselt den Endpoint, kümmert sich um Retries und liefert typisierte Fehler:

• PHP — Captcha-La/captchala-php (中文)
• Go — go get github.com/Captcha-La/captchala-go · README

Nachdem der Nutzer das Frontend-CAPTCHA bestanden hat, muss Ihr Server den vom SDK zurückgegebenen Token validieren. Nachfolgend die serverseitigen Validierungs-Endpoints.

Serverseitige Token-Validierung

Validieren Sie den pass_token aus dem Frontend-SDK (mit pt_-Präfix). Erfordert die Header X-App-Key und X-App-Secret.

POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

TIP

Prüfen Sie data.valid === true und dass data.action mit der erwarteten Szene übereinstimmt (weisen Sie einen Token aus einem pay-Flow zurück, wenn er an /login präsentiert wird). Tokens sind Einmal-Tokens.

Servergenerierter Challenge-Token

Stellen Sie einen kurzlebigen server_token aus Ihrem Backend heraus aus. Der Browser übergibt diesen Token anschließend bei der Initialisierung einer Challenge und beweist damit, dass die Anfrage von Ihrem vertrauenswürdigen Server stammt.

Server-Token ausstellen

Rufen Sie diesen Endpoint ausschließlich von Ihrem eigenen Server aus auf. Erfordert X-App-Key + X-App-Secret. Die Antwort enthält einen server_token (sct_-Präfix), den das Frontend an die Challenge-Initialisierung weiterreicht.

POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4

{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}

Body-Parameter (form-urlencoded)

Feld	Beschreibung
action	Business-Szene, z. B. login, register, pay. Muss mit der bei der Challenge-Initialisierung verwendeten action übereinstimmen.
ttl	Token-Lebensdauer in Sekunden. Standard 300, Maximum 900.
max_uses	Maximale Anzahl an Einlösungen des Tokens. Standard 10.
bind_ip	Bindet den Token an eine Client-IP. Eine Initialisierung von einer anderen IP wird abgewiesen.
bind_device_id	Bindet den Token an eine bestimmte Geräte-ID.
bind_fingerprint	Bindet den Token an einen bestimmten Browser-Fingerprint.

Challenge initialisieren

Wird vom SDK aufgerufen, um eine CAPTCHA-Challenge zu starten. Akzeptiert einen optionalen, von /v1/server/challenge/issue ausgestellten server_token.

Feld	Beschreibung
app_key	Ihr öffentlicher App Key.
action	Business-Szene. Muss mit der beim Ausstellen des server_token verwendeten action übereinstimmen.
server_token	Optional; erforderlich, wenn für die Anwendung server_token_required = true gesetzt ist.

INFO

Ist server_token_required für diese Anwendung im Dashboard aktiviert, weist die Challenge-Initialisierung Anfragen ohne gültigen server_token zurück.

Fehlercodes

Code	Beschreibung
invalid_app_key	Ungültiger App Key
invalid_app_secret	Ungültiges App Secret
challenge_expired	Challenge abgelaufen
challenge_not_found	Challenge nicht gefunden
invalid_answer	Ungültige Antwort
token_expired	Token abgelaufen
token_already_used	Token bereits verwendet
token_not_found	Token nicht gefunden
quota_exceeded	Kontingent überschritten
rate_limited	Rate Limit erreicht
rate_limit_exceeded	Zu viele Ausstellungs-Anfragen für diese Anwendung. Bitte zurückfahren und erneut versuchen.