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 ReklamSMS 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://smskolay.net/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

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 ISO8601 (örn. 2025-12-31T23:59:00+03:00) verildiğinde kayıt kuyruğa alınır.

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

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.