# auth.md — esim.tc

Bu belge, esim.tc'ye program aracılığıyla erişen ajanlar ve LLM'ler için kimlik
doğrulama durumunu açıklar. Kapsam bilerek dardır ve olduğundan fazlasını vaat
etmez: **okuma serbesttir, satın alma insana bağlıdır.**

- Kaynak sunucu: `https://esim.tc/api`
- API tanımı: <https://esim.tc/openapi.json>
- API kataloğu: <https://esim.tc/.well-known/api-catalog>
- Son güncelleme: 07.08.2026

## Kimin için

eSIM paketlerini, ülke kapsamlarını ve fiyatları okumak isteyen ajanlar için.
Kullanıcı adına sipariş vermek isteyen ajanlar için değil — aşağıya bakın.

## Kimlik doğrulaması gerekmeyen uçlar

Kataloğun tamamı anonim erişime açıktır. API anahtarı, kayıt, token ya da
`Authorization` başlığı **gerekmez**:

- `GET /api/countries`, `GET /api/country/{uIdOrUrl}`
- `GET /api/country/products/{uIdOrUrl}`
- `GET /api/regions`, `GET /api/region/{uIdOrUrl}`
- `GET /api/region/products/{uIdOrUrl}`
- `GET /api/product/{uId}`, `GET /api/products/best`, `GET /api/products/sameplans`

Sayfaların markdown sürümleri de anonim erişime açıktır: yolun sonuna `.md`
ekleyin ya da `Accept: text/markdown` başlığı gönderin. İndeks:
<https://esim.tc/llms.txt>

Bu uçlarda IP başına 60 saniyede 300 istek sınırı vardır. Sınır aşılırsa
`429 Too Many Requests` ve `Retry-After` başlığı döner. Eşik, insan kullanıcının
onlarca katı; kaçak döngüleri durdurmak için var, sizi kısıtlamak için değil.
Yine de ülke ve bölge listelerini en az bir saat önbelleğe alın.

## Kimlik doğrulaması gereken uçlar

Sipariş, cüzdan, kullanıcı profili ve eSIM kota sorgusu uçları JWT ister:

```
Authorization: Bearer <token>
```

Token yalnızca bir insanın <https://esim.tc/giris> adresinde e-posta + şifre ya da
Google/Apple ile oturum açmasıyla üretilir. Bu uçlar `openapi.json` içinde
**belgelenmez**; kararlı bir sözleşme olarak sunulmuyorlar ve haber verilmeden
değişebilirler.

## Ajan kaydı (agent registration)

**Şu anda yok.** Ajanların programatik olarak hesap açabileceği, istemci
kaydedebileceği ya da kimlik bilgisi alabileceği bir uç bulunmuyor. `POST` ile
denemeyin; böyle bir uç yok, deneme yanılma yalnızca hız sınırına takılmanıza yol
açar.

Kataloğu ticari bir üründe kullanmak ya da bir entegrasyon konuşmak isterseniz:
**info@esimtr.com**

## OAuth keşif belgeleri neden yayınlanmıyor

`/.well-known/openid-configuration` ve `/.well-known/oauth-protected-resource`
**bilerek** yayınlanmıyor. esim.tc bir OAuth yetkilendirme sunucusu değildir;
Google ve Apple ile oturum açmada yetkilendiren taraf değil, güvenen taraftır
(relying party). Yayınlanacak bir `issuer`, `token_endpoint` ya da `jwks_uri`
yok. Var gibi göstermek, çalışmayan uçlara yönlendirilen istemciler demek olurdu.

Bu durum değişirse bu belge ve
[API kataloğu](https://esim.tc/.well-known/api-catalog) birlikte güncellenir.

## Kimlik bilgisi kullanımı — ajanlar için kurallar

Bir kullanıcının oturumuyla çalışıyorsanız:

- Kullanıcıdan esim.tc şifresini **istemeyin**. Şifre girilecek tek yer
  esim.tc'nin kendi giriş sayfasıdır.
- Token'ı log'a yazmayın, üçüncü taraf bir servise göndermeyin, oturum dışına
  taşımayın.
- Token'ı yalnızca `esim.tc` alan adına, yalnızca `Authorization` başlığında
  gönderin. Sorgu parametresine koymayın.
- Ödeme, sipariş iptali ve iade gibi geri alınamaz işlemleri kullanıcı açıkça
  onaylamadan çalıştırmayın.
- Satın alma akışı 3D Secure doğrulaması ister ve insan onayı bekler; bunu
  otomatikleştirmeye çalışmayın.

## İlgili belgeler

- Geliştirici dokümantasyonu: <https://esim.tc/gelistirici>
- OpenAPI tanımı: <https://esim.tc/openapi.json>
- İçerik kullanım tercihleri: <https://esim.tc/robots.txt> (`Content-Signal`)
- Site indeksi: <https://esim.tc/llms.txt>