---
title: "Geliştirici ve Ajan Dokümantasyonu | esim.tc API"
description: "esim.tc'nin herkese açık eSIM katalog API'si. Ülkeler, bölgeler ve paket fiyatları için kimlik doğrulaması gerektirmeyen uçlar, OpenAPI tanımı ve ajanlar için keşif dosyaları."
url: https://esim.tc/gelistirici
site: "eSIM Türkiye"
updated: "07.08.2026"
---

# Geliştirici ve Ajan Dokümantasyonu

eSIM paket kataloğumuz — ülkeler, kapsamlar ve fiyatlar — herkese açıktır. API anahtarı, kayıt ya da token gerekmez. Bu sayfa insanlar için; makineler için hazırlanmış sürüm [openapi.json](https://esim.tc/openapi.json) dosyasındadır.

## Hızlı başlangıç

Temel adres `https://esim.tc`. Bütün uçlar `GET` ve hepsi anonim.

`curl https://esim.tc/api/countries`

`curl "https://esim.tc/api/country/products/yunanistan?page=1&size=5"`

İlk çağrı ülkeleri paket sayılarıyla verir, ikincisi Yunanistan'da geçerli paketleri fiyata göre sıralar. Ülkeyi UUID yerine sayfa adresindeki Türkçe slug ile de çağırabilirsiniz — `yunanistan`, `japonya`, `abd` gibi.

## Uçlar

| Uç | Ne döner |
| --- | --- |
| `GET /api/countries` | Tüm ülkeler, paket sayılarıyla. Aranma sayısına göre sıralı |
| `GET /api/country/{uIdOrUrl}` | Tek ülke |
| `GET /api/country/products/{uIdOrUrl}` | Ülkede geçerli paketler, sayfalı |
| `GET /api/regions` | Tüm bölgeler |
| `GET /api/region/{uIdOrUrl}` | Tek bölge |
| `GET /api/region/products/{uIdOrUrl}` | Bölgede geçerli paketler, sayfalı |
| `GET /api/product/{uId}` | Tek paketin tüm ayrıntıları |
| `GET /api/products/best` | Çok satan paketler |
| `GET /api/products/sameplans?uId=` | Aynı **destinasyonu** kapsayan diğer paketler (adı yanıltıcı, kota/gün eşleşmesi garanti değil) |

Parametrelerin tamamı ve alan açıklamaları için [OpenAPI tanımına](https://esim.tc/openapi.json) bakın.

## Yanıt zarfı

Her yanıt aynı zarfla gelir; asıl veri `data` alanındadır.

`{ "success": true, "statusCode": 200, "message": "İstek başarıyla gerçekleşti.", "data": ... }`

## Hata davranışı

Burada dikkatli olun: **kayıt bulunamadığında da HTTP 400 döner**, 404 değil. Hata türünü ayırt etmek için HTTP durum koduna değil `success` ve `message` alanlarına bakın. Mesajlar Türkçedir.

## Fiyatlar ve birimler

`price` alanı Türk Lirası (TRY) cinsinden ve KDV dahildir. `quota` alanı `quotaType` ile birlikte okunur, `validDays` ise paketin ilk aktivasyondan sonraki geçerlilik süresidir. Ülke kodları ISO 3166-1 alpha-2 ve **küçük harftir** (`gr`, `jp`, `us`).

## Bilmeniz gereken üç davranış

Bunlar API'nin gerçek davranışı; sürpriz olmasın diye yazıyoruz.

**Paket listeleri tekilleştirilmiştir.** Ülke ve bölge listelerinde aynı (kota, gün) kombinasyonundan yalnızca en ucuz paket döner. Yani tek bir ülke için beş sağlayıcının 5 GB / 30 günlük paketini görmezsiniz, en ucuzunu görürsünüz. Gizlenen alternatifler için `sameplans` ucunu kullanın — ama dikkat, o uç aynı kota/günü değil aynı **destinasyonu** kapsayan paketleri döndürür, eşleştirmeyi kendiniz yapmanız gerekir.

**Liste uçlarında bazı alanlar boş gelir.** `name`, `providerName` ve `isActive` yalnızca tekil paket ucunda (`/api/product/{uId}`) doludur. Listede `isActive` alanı `false` görünse de listeler zaten yalnızca aktif paketleri içerir.

**`productCount` alanına dikkat.** Tekil ülke ucunda her zaman 0'dır — ülke paket sayıları için `/api/countries` yanıtını kullanın. Bölge uçlarında ise hem listede hem tekilde her zaman 0'dır; bölgedeki paket sayısı için `/api/region/products/{slug}` yanıtındaki `itemCount` alanına bakın.

## Hız sınırı

IP başına **60 saniyede 300 istek**. Aşarsanız `429 Too Many Requests` ve `Retry-After` başlığı alırsınız.

Bu eşik normal kullanımı kısıtlamak için değil, kaçak döngüleri durdurmak için var. Karşılaştırma olsun diye: sitenin kendi arayüzünde soğuk bir paket sayfası yüklemesi 4 istek, bir filtre değişimi 1 istek. En hırslı insan kullanıcı bile dakikada 30 isteği zor geçiyor.

Yine de birkaç ricamız var:

- Ülke ve bölge listelerini en az bir saat önbelleğe alın. `/api/regions` yanıtının neredeyse tamamı base64 gömülü bölge ikonlarıdır.
- `/api/countries` sunucu tarafında 10 dakika önbelleklenir; sık çağırmak size daha taze veri getirmez.

## Kimlik doğrulama

Katalog uçlarının hiçbiri kimlik doğrulaması istemez. Sipariş, cüzdan ve profil uçları JWT ister ve bunlar bilerek belgelenmez — kararlı bir sözleşme olarak sunulmuyorlar. Ajanların programatik olarak hesap açabileceği ya da kimlik bilgisi alabileceği bir uç yok.

Gerekçesiyle birlikte tam açıklama: [auth.md](https://esim.tc/auth.md)

## Ajanlar için keşif dosyaları

| Dosya | İçeriği |
| --- | --- |
| [/.well-known/api-catalog](https://esim.tc/.well-known/api-catalog) | RFC 9727 API kataloğu |
| [/openapi.json](https://esim.tc/openapi.json) | OpenAPI 3.1 tanımı |
| [/auth.md](https://esim.tc/auth.md) | Kimlik doğrulama durumu |
| [/llms.txt](https://esim.tc/llms.txt) | Site indeksi |
| [/llms-full.txt](https://esim.tc/llms-full.txt) | İçerik sayfalarının tam metni |
| [/robots.txt](https://esim.tc/robots.txt) | Tarama kuralları ve `Content-Signal` tercihleri |

Ayrıca her sayfanın markdown sürümü var: yolun sonuna `.md` ekleyin ya da `Accept: text/markdown` başlığı gönderin.

## İletişim

Kataloğu ticari bir üründe kullanmak, bir entegrasyon konuşmak ya da bir hata bildirmek isterseniz **info@esimtr.com** adresine yazın.