Anahtarınızı panelde API ve webhook ekranından oluşturursunuz; anahtar yalnız oluşturulduğu anda gösterilir. Panelde aynı belge örnekleriyle /gelistirici/belgeler sayfasındadır.
Kimlik ve sınırlar
- Başlık:
Authorization: Bearer mk_…ya daX-Api-Anahtari: mk_…. - Numara Türkiye için
05321112233,5321112233ya da+905321112233; yanıtta E.164 (+90…) döner. - Anahtar başına dakikada 1200 istek (aşılırsa 429
HIZ_SINIRI). İsteğe bağlı IP kısıtı.
Gönder: POST /mesajlar
Eş adlar: /messages, /sms. İngilizce alan adları da kabul edilir.
İstek gövdesi
{
"alici": "05321112233",
"metin": "Siparişiniz yola çıktı",
"kanal": "SMS",
"disKimlik": "siparis-1042"
}| Alan | Eş ad | Açıklama |
|---|---|---|
alici / alicilar[] | to | Tek numara ya da dizi (en çok 1000) |
iletiler[] | messages[] | Her biri kendi alici, metin, disKimlik… alanlarıyla |
metin | text | En çok 4000 karakter |
kanal | channel | SMS (varsayılan firma ayarı) ya da WHATSAPP |
cihazId | deviceId | Yalnız bu telefondan gönder |
simSlot | sim | 0 = SIM 1, 1 = SIM 2 |
yedekSms | fallbackSms | WhatsApp gönderilemezse SMS'e düş (varsayılan firma ayarı) |
disKimlik | externalId | Kendi kimliğiniz; aynı değerle tekrar gönderim yeni ileti açmaz, ilk iletiyi döndürür |
planlanan | scheduledAt | ISO-8601 ileri tarih (2026-10-25T09:00:00+03:00) |
Yanıt 201
{ "tamam": true, "sayi": 1, "iletiler": [ { "id": 123, "durum": "KUYRUKTA", "alici": "+905321112233" } ] }İstekteki herhangi bir hata isteğin tamamını reddeder; yarım gönderim olmaz.
GET /gonder?anahtar=mk_…&alici=0532…&metin=Merhaba (isteğe bağlı &kanal=WHATSAPP). Anahtar adres satırında gittiği için yalnız HTTPS ve sunucudan sunucuya kullanın.Örnekler
curl
curl -X POST https://mesajra.tanitek.com.tr/api/v1/mesajlar \
-H "Authorization: Bearer mk_..." -H "Content-Type: application/json" \
-d '{"alici":"05321112233","metin":"Merhaba"}'PHP
$c = curl_init("https://mesajra.tanitek.com.tr/api/v1/mesajlar");
curl_setopt_array($c, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer mk_...", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["alici" => "05321112233", "metin" => "Merhaba"])]);
echo curl_exec($c);Python
import requests
requests.post("https://mesajra.tanitek.com.tr/api/v1/mesajlar", headers={"Authorization": "Bearer mk_..."},
json={"alici": "05321112233", "metin": "Merhaba"}).json()Zamanlı WhatsApp, SMS'e düşmeli
curl -X POST https://mesajra.tanitek.com.tr/api/v1/mesajlar \
-H "Authorization: Bearer mk_..." -H "Content-Type: application/json" \
-d '{"alici":"05321112233","metin":"Yarın 10:30 randevunuz var.","kanal":"WHATSAPP","yedekSms":true,"planlanan":"2026-10-25T09:00:00+03:00","disKimlik":"randevu-5512"}'Sorgula
| Uç | Ne döner |
|---|---|
GET /mesajlar/:id | Tek ileti |
GET /mesajlar/dis/:disKimlik | Kendi kimliğinizle ileti |
GET /mesajlar?durum=BASARISIZ&bas=2026-10-01&bit=2026-10-22&sayfa=1&adet=100 | Süzgeçli liste |
POST /mesajlar/:id/iptal | PLANLI, KUYRUKTA ya da ATANDI iletiyi iptal eder |
GET /telefonlar | Telefonlar ve çevrimiçi durumu |
GET /hesap | Plan, aylık hak, bu ay kullanım, kuyrukta bekleyen, açık özellikler |
GET /gelen?sonraki=<id> | Telefonlara gelen SMS'ler (artan id; kaldığınız yerden) |
Durumlar
PLANLI → KUYRUKTA → ATANDI (telefon aldı) → GONDERILIYOR → GONDERILDI (operatöre çıktı) → ILETILDI (teslim raporu). Yan dallar: BASARISIZ, IPTAL (hataKodu: RET_LISTESI = alıcı ret listesinde).
Durum yalnız ileri gider: geç gelen eski bir rapor durumu geri almaz. Telefona verilip 10 dakika raporlanmayan ileti kuyruğa döner; gönderim sırasında takılan ileti çift gitmesin diye yeniden kuyruğa alınmaz.
Hatalar
Gövde her zaman { "mesaj": "…", "kod": "…" }.
| HTTP | kod | Ne zaman |
|---|---|---|
| 400 | ALICI_YOK, METIN_YOK, … | Doğrulama |
| 401 | ANAHTAR_YOK, ANAHTAR_GECERSIZ | Anahtar yok, kapalı ya da silinmiş |
| 402 | ABONELIK_KILITLI | Deneme bitti ya da ödeme alınamadı |
| 403 | PLAN_OZELLIK, IP_KISITI | Özellik planınızda yok / IP izinli değil |
| 409 | TEKRAR | Aynı alıcıya aynı metin kısa sürede ikinci kez |
| 429 | KOTA_DOLDU, HIZ_SINIRI | Aylık ileti hakkı doldu / dakika sınırı |
Webhook
Panelden adres ve olaylar seçilir: ileti.gonderildi, ileti.iletildi, ileti.basarisiz, gelen.sms, cihaz.cevrimdisi. Gövde { "olay": "ileti.iletildi", "zaman": "…", "veri": { … } }.
- Başlıklar:
X-Mesajra-Olay,X-Mesajra-Zaman(unix saniye),X-Mesajra-Imza: sha256=<hex>. - İmza = HMAC-SHA256(gizli,
"<zaman>.<ham gövde>"). - 2xx dışı yanıtta 1, 5, 30, 120 ve 720 dakika sonra yeniden denenir.
Doğrulama (Node.js)
const beklenen = "sha256=" + crypto.createHmac("sha256", GIZLI)
.update(`${req.headers["x-mesajra-zaman"]}.${hamGovde}`).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(beklenen), Buffer.from(req.headers["x-mesajra-imza"])))
return res.status(401).end();
// Tekrar saldırısına karşı: |şimdi - zaman| < 300 snDoğrulama (PHP)
$govde = file_get_contents("php://input");
$zaman = $_SERVER["HTTP_X_MESAJRA_ZAMAN"];
$beklenen = "sha256=" . hash_hmac("sha256", $zaman . "." . $govde, $GIZLI);
if (!hash_equals($beklenen, $_SERVER["HTTP_X_MESAJRA_IMZA"]) || abs(time() - (int)$zaman) > 300) { http_response_code(401); exit; }Sorumluluk
API'yle gönderdiğiniz iletilerin içeriği ve alıcıları sizin kararınızdır. Ticari ileti göndermeden önce alıcının onayını ve İYS kaydını kontrol edin; ayrıntı ticari ileti ve İYS sayfasında. Konu için SMS API entegrasyonu rehberimize de bakabilirsiniz.