---
title: API Referansı
---

# API Referansı

CaptchaLa, tüm sunucu tarafı entegrasyonlar için RESTful API sağlar.

## Temel URL

```
https://apiv1.captcha.la
```

## Kimlik Doğrulama

Tüm API istekleri kimlik doğrulama başlıkları gerektirir:

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

::: warning
`X-App-Secret` yalnızca sunucu tarafıdır. Asla tarayıcılara, mobil uygulamalara veya genel depolara açmayın.
:::

## Sunucu Tarafı Doğrulama API'si

> 💡 **Standart kodu atlamak için bir sunucu SDK'sı kullanın.** Uç noktayı sarar, yeniden denemeleri yönetir, tipli hataları yüzeye çıkarır:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

Kullanıcı frontend CAPTCHA'yı geçtikten sonra sunucunuzun, SDK tarafından döndürülen token'ı doğrulaması gerekir. Aşağıda sunucu tarafı doğrulama uç noktaları yer alır.

### Sunucu Tarafı Token Doğrulama

Frontend SDK'dan gelen pass_token'ı (pt_ ön ekli) doğrular. X-App-Key ve X-App-Secret başlıklarını gerektirir.

```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` isteğe bağlıdır ancak önerilir — gelen isteğinizdeki son kullanıcının IP'si, ek risk kontrolleri için kullanılır; atlanması güvenlidir.

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

`captcha_args` bilgilendirme amaçlı verilerdir (günlükleme / risk kullanımınız için): `platform`, `user_ip` (çözüm anındaki IP), `referer`, `pkg`, `solved_at`, `risk_score`.

::: tip
`data.valid === true` olduğunu **ve** `data.action` değerinin beklediğiniz senaryoyla eşleştiğini doğrulayın
(bir `pay` akışına ait token `/login` adresinde sunulursa reddedin). Token'lar tek kullanımlıktır.
:::

## Sunucu Tarafından Düzenlenen Challenge Token'ı {#server-token}

Backend'inizden kısa ömürlü bir server_token düzenleyin. Tarayıcı, bir challenge başlatırken bu token'ı ileterek isteğin güvenilir sunucunuzdan kaynaklandığını kanıtlar.

### Sunucu Token'ı Düzenle

Bu uç noktayı yalnızca kendi sunucunuzdan çağırın. X-App-Key + X-App-Secret gerektirir. Yanıt, frontend'in challenge başlatma çağrısına ileteceği bir server_token (sct_ ön ekli) içerir.

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

#### Gövde Parametreleri (form-urlencoded)

| Alan | Açıklama |
| --- | --- |
| `action` | İş senaryosu, örn. login, register, pay. Challenge başlatmada kullanılan action ile eşleşmelidir. |
| `ttl` | Token'ın saniye cinsinden ömrü. Varsayılan 300, maksimum 900. |
| `max_uses` | Token'ın tüketilebileceği maksimum sayı. Varsayılan 10. |
| `bind_ip` | Token'ı bir istemci IP'sine bağlar. Başka bir IP'den başlatma reddedilir. |
| `bind_device_id` | Token'ı belirli bir cihaz id'sine bağlar. |
| `bind_fingerprint` | Token'ı belirli bir tarayıcı parmak izine bağlar. |

### Challenge Başlat

CAPTCHA challenge'ı başlatmak için SDK tarafından çağrılır. /v1/server/challenge/issue tarafından düzenlenen isteğe bağlı bir server_token kabul eder.

| Alan | Açıklama |
| --- | --- |
| `app_key` | Genel App Key'iniz. |
| `action` | İş senaryosu. server_token düzenlenirken kullanılan action ile eşleşmelidir. |
| `server_token` | İsteğe bağlı; uygulamada server_token_required = true olduğunda gereklidir. |

::: info
Bu uygulama için panelde server_token_required etkinleştirilmişse, challenge başlatma geçerli bir server_token taşımayan istekleri reddeder.
:::

## Hata Kodları

| Kod | Açıklama |
| --- | --- |
| `invalid_app_key` | Geçersiz App Key |
| `invalid_app_secret` | Geçersiz App Secret |
| `challenge_expired` | Challenge süresi doldu |
| `challenge_not_found` | Challenge bulunamadı |
| `invalid_answer` | Geçersiz yanıt |
| `token_expired` | Token süresi doldu |
| `token_already_used` | Token zaten kullanıldı |
| `token_not_found` | Token bulunamadı |
| `quota_exceeded` | Kota aşıldı |
| `rate_limited` | Hız sınırına ulaşıldı |
| `rate_limit_exceeded` | Bu uygulama için çok fazla düzenleme isteği. Geri çekilip yeniden deneyin. |