API-Referenz

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

Basis-URL

https://apiv1.captcha.la

Nur eine Basis-URL

Alle Endpunkte auf dieser Seite liegen auf apiv1.captcha.la. Die Standby-Hosts (bypass.*, fallbackapiv1.*) sind Failover-Ziele, die die SDKs bei einem Ausfall selbst ansteuern — richtet man die eigene Integration darauf, kommt service_online zurück.

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.

bash

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

client_ip ist optional, aber empfohlen: die IP des Endnutzers aus Ihrer eingehenden Anfrage, die für zusätzliche Risikoprüfungen verwendet wird. Sie können es problemlos weglassen.

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}

Das captcha_args-Objekt ist rein informativ (für Ihr Logging / Ihre Risikoanalyse):

Feld	Beschreibung
`platform`	Plattform, von der die Challenge gelöst wurde.
`user_ip`	Zum Lösungszeitpunkt erfasste IP.
`referer`	Referer-URL der Challenge-Seite.
`pkg`	Paket-Identifier der App (mobil), falls zutreffend.
`solved_at`	Unix-Zeitstempel der Lösung.
`risk_score`	Risiko-Score der Lösungssitzung.

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.

bash

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

json

{
  "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.

Offline-Fallback-Endpunkte

CaptchaLa betreibt auf separaten Hosts einen Standby-Dienst, damit die Verifizierung auch dann funktioniert, wenn die Haupt-API nicht erreichbar ist:

Host	Aufgerufen von	Zweck
`bypass.captchala.com` · `bypass.captcha-cdn.net`	Web-/Native-SDK (Endnutzerseite)	Führt während eines Ausfalls die Offline-Verifizierung durch und stellt ein `offline_`-Pass-Token aus
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	Server-SDKs	Validiert `offline_`-Tokens (`POST /api/validate`)

Das sind Failover-Ziele, keine alternative API. Die SDKs wechseln von sich aus dorthin — erst nachdem die Haupt-API tatsächlich ausgefallen ist — und wechseln nach der Wiederherstellung automatisch zurück. Nichts in Ihrer Konfiguration sollte auf diese Hosts zeigen.

`service_online` (HTTP 503)

json

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Sie bekommen diesen Fehler, solange die Haupt-API läuft: Der Standby-Dienst bedient Traffic nur während eines Ausfalls. Die Anfrage ging an bypass.* statt an https://apiv1.captcha.la — korrigieren Sie die URL, Wiederholungen helfen nicht.

Häufige Ursachen:

Ursache	Lösung
SDK-Option `apiServer` zeigt auf einen Bypass-Host	Auf `https://apiv1.captcha.la` setzen oder die Option entfernen und das SDK wählen lassen
`bypassServers` von Hand überschrieben	Überschreibung entfernen, sofern wir Ihnen keine konkreten Hosts genannt haben
Eigener HTTP-Client hat eine Bypass-URL übernommen (z. B. während eines Vorfalls aus den Devtools)	`https://apiv1.captcha.la` aufrufen und das Failover dem SDK überlassen — der Standby-Dienst nimmt keinen normalen Challenge-Traffic an
Load Balancer / Proxy / DNS schreibt den API-Host um	Upstream wieder auf `apiv1.captcha.la` zeigen lassen

TIP

Auch die serverseitige Validierung braucht den Fallback-Host nicht: POST /v1/validate auf apiv1.captcha.la genügt, und die PHP-/Go-Server-SDKs verifizieren offline_-Tokens automatisch über die Backup-API.

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.
`service_online`	Anfrage traf den Offline-Fallback-Dienst, während die Haupt-API online ist. Stattdessen `https://apiv1.captcha.la` aufrufen — siehe Offline-Fallback-Endpunkte.

API-Referenz ​

Basis-URL ​

Authentifizierung ​

Serverseitige Validierungs-API ​

Serverseitige Token-Validierung ​

Servergenerierter Challenge-Token ​

Server-Token ausstellen ​

Body-Parameter (form-urlencoded) ​

Challenge initialisieren ​

Offline-Fallback-Endpunkte ​

service_online (HTTP 503) ​

Fehlercodes ​

API-Referenz

Basis-URL

Authentifizierung

Serverseitige Validierungs-API

Serverseitige Token-Validierung

Servergenerierter Challenge-Token

Server-Token ausstellen

Body-Parameter (form-urlencoded)

Challenge initialisieren

Offline-Fallback-Endpunkte

`service_online` (HTTP 503)

Fehlercodes