---
title: API Referansı
---

# API Referansı

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

## Temel URL

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

::: warning Tek bir temel URL
Bu sayfadaki tüm uç noktalar `apiv1.captcha.la` üzerindedir. Yedek ana makineler (`bypass.*`, `fallbackapiv1.*`), kesinti sırasında SDK'ların kendiliğinden yöneldiği devralma hedefleridir — entegrasyonunuzu oraya yöneltirseniz [`service_online`](#offline-fallback) döner.
:::

## 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.
:::

## Çevrimdışı yedek uç noktalar {#offline-fallback}

CaptchaLa, ana API'ye ulaşılamadığında doğrulamanın sürmesi için ayrı ana makinelerde bir yedek servis çalıştırır:

| Ana makine | Çağıran | Amaç |
| --- | --- | --- |
| `bypass.captchala.com` · `bypass.captcha-cdn.net` | Web / native SDK (son kullanıcı tarafı) | Ana API kapalıyken çevrimdışı doğrulamayı yapar ve `offline_` pass token üretir |
| `fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net` | Sunucu SDK'ları | `offline_` token'larını doğrular (`POST /api/validate`) |

**Bunlar devralma hedefidir, alternatif bir API değildir.** SDK'lar yalnızca ana API gerçekten başarısız olduktan sonra kendiliğinden buraya geçer ve ana API toparlanınca geri döner. Kendi yapılandırmanızdaki hiçbir şey bu adresleri göstermemelidir.

### `service_online` (HTTP 503)

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

Ana API ayaktayken bu hatayı alırsınız: yedek servis yalnızca kesinti sırasında trafik kabul eder. İstek `https://apiv1.captcha.la` yerine `bypass.*` adresine gitmiştir — URL'yi düzeltin, yeniden denemek işe yaramaz.

Sık görülen nedenler:

| Neden | Çözüm |
| --- | --- |
| SDK `apiServer` seçeneği bir bypass adresine ayarlı | `https://apiv1.captcha.la` yapın ya da seçeneği kaldırıp sunucuyu SDK seçsin |
| `bypassServers` elle geçersiz kılınmış | Size özel adresler vermediysek bu geçersiz kılmayı kaldırın |
| Kendi HTTP istemciniz bypass URL'sini kopyalamış (ör. olay sırasında devtools'tan) | `https://apiv1.captcha.la` çağırın, devralmayı SDK'ya bırakın — yedek servis normal challenge trafiğini kabul etmez |
| Yük dengeleyici / proxy / DNS API adresini yeniden yazıyor | Upstream'i yeniden `apiv1.captcha.la` yapın |

::: tip
Sunucu tarafı doğrulama da yedek adrese ihtiyaç duymaz: `apiv1.captcha.la` üzerinde `POST /v1/validate` yeterlidir; `offline_` token'larını PHP / Go sunucu SDK'ları yedek API üzerinden otomatik doğrular.
:::

## 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. |
| `service_online` | Ana API çalışırken istek çevrimdışı yedek servise ulaştı. Bunun yerine `https://apiv1.captcha.la` kullanın — bkz. [Çevrimdışı yedek uç noktalar](#offline-fallback). |