API Entegrasyon Dokümanı

REST API ile SMS Entegrasyon Kılavuzu

✓ API Durumu: Sistem tamamen çalışır durumda! Kendi yazılımınızdan veya web sitenizden API'yi kullanarak hesabınızdaki gerçek SMS kredilerini kullanabilirsiniz. Her SMS gönderimi otomatik olarak kredilerinizden kesilir.

Bu doküman, yazılımınızdan Anadolu SMS hesabınızdaki kredileri kullanarak SMS göndermek için gerekli tüm REST API detaylarını, güvenlik kurallarını ve örnekleri içerir.

1. Temel Bilgiler

Taban URL: https://anadolusms.com/api/v1 (uzantısız URL desteklenir)
İçerik Tipi: application/json
Kimlik: Authorization: Bearer <API_KEY> (her kullanıcı için tek anahtar)
Idempotency (önerilir): Idempotency-Key: <UUID>
CORS: Tüm uçlar GET, POST, OPTIONS destekler; preflight'a 204 döner

2. Telefon Formatı ve Başlık

Telefon: +905XXXXXXXXX, 90XXXXXXXXXX, 05XXXXXXXXX formatları kabul edilir (otomatik normalize edilir)
Originator: /api/v1/originators ile listenizi alın; parametre originator

2.1. SMS Ücretlendirme ve Hesaplama

Hesaplama Mantığı: API'deki SMS ücretlendirmesi, kullanıcı panelindeki hesaplama mantığı ile tamamen aynıdır. Sistemde 2 SMS görünen bir mesaj, API'den gönderildiğinde de 2 SMS kredisi düşülür.

Hesaplama Yöntemi: Her zaman Türkçe karakter seti (tr2) olarak hesaplanır
Operator Code: Her mesaja otomatik olarak +5 karakter eklenir (B*** kodu için)
Karakter Limitleri:
- Tek SMS: 155 karakter (operator code dahil)
- Çoklu SMS: Her bölüm 155 karakter (operator code dahil)
Özel Karakterler: GSM extension karakterleri (|, ^, {, }, [, ], \, ~, €) 2 karakter sayılır
Unicode Temizleme: Unicode karakterler otomatik temizlenir (Türkçe harfler hariç: ğ, Ğ, ş, Ş, ı, İ, ç, Ç, ö, Ö, ü, Ü)
Maksimum Bölüm: En fazla 8 SMS bölümü gönderilebilir
Maliyet Hesaplama: parts × recipient_count (örn: 2 bölümlü mesaj × 10 alıcı = 20 SMS kredisi)

Önemli: Mesajınız API'ye gönderilmeden önce otomatik olarak işlenir (Unicode temizleme, encoding dönüşümü vb.). Bu işlemler user-panel ile aynı şekilde yapıldığı için hesaplama sonuçları her zaman tutarlıdır.

3. Uç Listesi

Metod	Endpoint	Açıklama
POST	`/sms/send`	Tek numara veya dizi olarak tek çağrıda gönderim
POST	`/sms/send-bulk`	Çoklu numara gönderimi (sınırsız; sunucu 1000'lik parçalara böler)
GET	`/account/balance`	Kredi sorgu
GET	`/originators`	Başlık listesi
GET	`/reports?send_id=ID`	Gönderim özet + detay (ilk 5000 satıra kadar)

4. Örnek — Tekli Gönderim

İstek:

POST /api/v1/sms/send Authorization: Bearer <API_KEY> Content-Type: application/json Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 { "to": "+9053XXXXXXX", "message": "Merhaba", "originator": "BASLIK", "schedule_at": null }

Başarılı Yanıt (200):

{ "send_id": 123, "event": "sent", "status": "sent", "parts": 1 }

Yetersiz Kredi Yanıtı (402):

{ "error": "Yetersiz kredi", "required": 125, "available": 40 }

5. Örnek — Toplu Gönderim

İstek:

POST /api/v1/sms/send-bulk Authorization: Bearer <API_KEY> Content-Type: application/json Idempotency-Key: 6a1e8a10-3c6f-4d1d-9f5c-2a9d5a77e201 { "to": ["+9053...","+9054...","+9055..."], "message": "Duyuru", "originator": "BASLIK" }

Başarılı Yanıt (200):

{ "batch_id": 124, "event": "sent", "status": "sent", "parts": 1, "queued": 3 }

6. Zamanlanmış Gönderim

schedule_at parametresi ISO8601 formatında (örn. 2025-12-31T23:59:00+03:00) verildiğinde kayıt kuyruğa alınır ve kredi hemen düşülür.

Önemli: Zamanlanmış SMS'ler için kredi hemen düşülür. Geçmiş tarih seçilemez. Zamanı gelmeden önce iptal edebilir veya tarihini güncelleyebilirsiniz.

Tarih Formatı ve Kurallar:

schedule_at parametresi mutlaka ISO8601 formatında olmalıdır (örn: 2025-12-31T23:59:00+03:00)
Timezone bilgisi dahil edilmelidir (örn: +03:00, -05:00)
Dakika seçimi 5 dakikalık dilimlerde olmalıdır: 00, 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55
Gönderim tarihi gelecekte olmalıdır (geçmiş tarih seçilemez)

İstek:

POST /api/v1/sms/send Authorization: Bearer <API_KEY> Content-Type: application/json { "to": "+9053...", "message": "Planlı", "originator": "BASLIK", "schedule_at": "2025-12-31T23:59:00+03:00" }

Yanıt (200):

{ "send_id": 125, "event": "queued", "status": "queued" }

Yetersiz Kredi (402) - Planlama anında kontrol edilir:

{ "error": "Yetersiz kredi", "required": N, "available": M }

Geçmiş Tarih (400):

{ "error": "Geçmiş bir tarih seçilemez. Lütfen gelecek bir tarih seçin." }

Geçersiz Tarih Formatı (400):

{ "error": "Geçersiz tarih formatı. ISO8601 formatında olmalıdır (örn: 2025-12-31T23:59:00+03:00). Hata: [detaylı hata mesajı]" }

5 Dakikalık Dilim Hatası (400):

{ "error": "Dakika seçimi 5 dakikalık dilimlerde olmalıdır (00, 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55)" }

7. Rapor Ucu

İstek:

GET /api/v1/reports?send_id=125 Authorization: Bearer <API_KEY>

Yanıt (200):

{ "summary": { "id": 125, "user_id": 1, "sender_name": "BASLIK", "message": "...", "send_type": "immediate|scheduled", "status": "pending|sending|completed|failed", "total_sent": 100, "success_count": 98, "failed_count": 2, "created_at": "...", "sent_at": "..." }, "details": [ { "phone_number": "+9053...", "status": "sent|failed|delivered", "error_message": null, "sent_at": "..." } ] }

8. Webhook (Opsiyonel, tavsiye edilir)

HTTPS zorunlu
Header'lar: X-Timestamp (epoch), X-Signature (sha256= + HMAC)
İmza: HMAC_SHA256(secret, X-Timestamp + '.' + body)
Olaylar: sms.queued, sms.sent, sms.failed

Webhook Örneği:

POST https://musteri.com/webhooks/sms X-Timestamp: 1730284500 X-Signature: sha256=f1a9... Content-Type: application/json { "event": "sms.sent", "send_id": 125, "count": 3, "failed": 0, "scheduled": true }

Doğrulama (pseudo-PHP):

$calc = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_TIMESTAMP'] . '.' . $body, $secret); if (!hash_equals($calc, $_SERVER['HTTP_X_SIGNATURE'])) http_response_code(401);

9. Hata Kodları ve Yanıtlar

HTTP Kodu	Açıklama
400	Geçersiz JSON / Eksik parametre
401	Kimlik doğrulama hatası (Bearer anahtar)
402	Yetersiz kredi
404	Kayıt bulunamadı (rapor)
429	Oran sınırı aşıldı (300 istek/dk)
500	Sağlayıcı/servis hatası

10. Oran Sınırı

Kullanıcı başına varsayılan: 300 istek/dk. İhtiyaca göre artırılabilir. Toplu gönderimler sunucu tarafında 1000'lik parçalara bölünerek hız/kararlılık dengelenir.

11. Yapılandırma

Ayarlar api/config.php üzerinden değiştirilebilir:

API_RATE_LIMIT_PER_MIN: Dakika başına istek limiti (varsayılan 300)
API_CHUNK_SIZE: API çağrılarında alt-parça boyutu (varsayılan 1000)
BATCH_MAX_GROUP: Zamanlanmış gönderimde tek kayıt içi üst grup (varsayılan 50000)
BATCH_API_CHUNK: Sağlayıcıya alt-parça boyutu (varsayılan 1000)
BATCH_DELAY_MS: Alt-parça arası gecikme (varsayılan 100 ms)
BATCH_FETCH_LIMIT: Her döngüde işlenecek kayıt sayısı (varsayılan 200)

12. Güvenlik Önerileri

API anahtarınızı sunucu tarafında tutun; istemci tarayıcıya vermeyin.
Webhook için HTTPS ve imza doğrulaması zorunlu kılın.
Opsiyonel IP whitelist uygulayabiliriz (talep üzerine).

Daha fazla bilgi ve yönetim için API Bilgisi sayfasını ziyaret edin.