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 Reklam 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://sizin-domain.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 (başlık): Zorunludur. Sadece hesabınıza atanmış başlıkları kullanın. GET /api/v1/originators ile listenizi alın; yanıt { "items": ["BASLIK1", "BASLIK2", ...] } formatındadır. Gönderim isteğinde originator alanına bu listeden bir değer yazın.

3. Uç Listesi

Metod	Endpoint	Açıklama
POST	`/sms/send`	Tek numara veya dizi (en fazla 1000 alıcı) ile gönderim. `originator` zorunludur.
POST	`/sms/send-bulk`	Çoklu numara gönderimi; `to` dizi olmalı. Sunucu 1000'lik parçalara böler. `originator` zorunludur.
GET	`/account/balance`	Kredi sorgu. Yanıt: `{ "credits": 123 }`
GET	`/originators`	Hesabınıza atanmış başlık listesi. Yanıt: `{ "items": ["BASLIK1", ...] }`
GET	`/reports?send_id=ID`	Gönderim özet + detay (ilk 5000 satıra kadar)

4. Örnek — Tekli Gönderim

Zorunlu alanlar: to, message, originator. Mesaj en fazla 1160 karakter (8 SMS bölümü).

İ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

Zorunlu alanlar: to (dizi), message, originator.

İ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. Dakika 5'in katı olmalıdır (00, 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55). Geçmiş tarih kabul edilmez.

İ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|btk_pending_approval|btk_blocked|cancelled", "total_sent": 100, "success_count": 98, "failed_count": 2, "created_at": "...", "sent_at": "..." }, "details": [ { "phone_number": "+9053...", "status": "sent|failed|delivered|pending", "error_message": null, "sent_at": "...", "delivered_at": "..." } ] }

Not: summary.status gönderim durumunu; details[].status her numara için teslimat durumunu gösterir. En fazla 5000 detay satırı döner.

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. Yanıt: `{ "error": "Yetersiz kredi", "required": N, "available": M }`
403	BTK riskli içerik; mesaj admin onayına alındı. Yanıt: `btk_blocked: true`, `reason`, `category`
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 (sunucu tarafı):

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 zamanlanmış 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.