toplusms.fun
Geliştiriciler için

SMS API Dokümantasyonu

toplusms.fun REST API ile kendi uygulamanızdan, web sitenizden veya otomasyonlarınızdan SMS gönderin; bakiyenizi ve kampanya sonuçlarınızı sorgulayın.

Kayıt ol, anahtar al

Giriş

Tüm istekler HTTPS üzerinden yapılır; istek ve yanıtlar JSON (UTF-8) biçimindedir.

Temel adreshttps://toplusms.fun/api/v1/
İçerik türüContent-Type: application/json
Sürümv1

Kimlik doğrulama

Her istekte API anahtarınızı Authorization başlığında gönderin. Anahtarı panelde API sayfasından oluşturursunuz; yalnızca oluşturduğunuzda bir kez gösterilir.

Authorization: Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatif olarak X-API-Key: <anahtar> başlığını da kullanabilirsiniz. Anahtarı URL içinde göndermeyin.

Hız sınırı

Her anahtar için dakikada en fazla 60 istek gönderebilirsiniz. Aşarsanız 429 ve Retry-After başlığı döner. Tek istekte en fazla 500 alıcıya gönderim yapılır; daha fazlası için isteği bölün.

POST SMS gönder

https://toplusms.fun/api/v1/send.php

AlanTürZorunluAçıklama
tometin veya diziEvetAlıcı numaraları. Dizi ya da virgül/boşlukla ayrılmış metin. Biçimler: 905XXXXXXXXX, 05XXXXXXXXX, +905XXXXXXXXX.
messagemetinEvetMesaj metni, en fazla 1000 karakter.
titlemetinHayırPanelde görünecek kampanya adı (en fazla 100 karakter).
sendermetinHayırGönderici başlığı (3-11 harf/rakam). Yalnızca hesabınızda özel başlığa izin verilmişse kullanılır; aksi halde varsayılan başlık kullanılır.
curl -X POST "https://toplusms.fun/api/v1/send.php" \
  -H "Authorization: Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":["905301112233","905304445566"],"message":"Merhaba, siparişiniz yola çıktı!","title":"Kargo bildirimi"}'
<?php
$ch = curl_init('https://toplusms.fun/api/v1/send.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to'      => ['905301112233', '905304445566'],
        'message' => 'Merhaba, siparişiniz yola çıktı!',
    ]),
]);
$yanit = json_decode(curl_exec($ch), true);
print_r($yanit);
import requests

r = requests.post(
    "https://toplusms.fun/api/v1/send.php",
    headers={"Authorization": "Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"to": ["905301112233", "905304445566"],
          "message": "Merhaba, siparişiniz yola çıktı!"},
    timeout=60,
)
print(r.status_code, r.json())
const res = await fetch("https://toplusms.fun/api/v1/send.php", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["905301112233", "905304445566"],
    message: "Merhaba, siparişiniz yola çıktı!",
  }),
});
console.log(res.status, await res.json());

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

{
  "status": "success",
  "campaign_id": 1042,
  "total": 2,
  "sent": 2,
  "failed": 0,
  "segments": 1,
  "cost": 2,
  "balance": 98,
  "invalid": [],
  "results": [
    { "to": "905301112233", "status": "sent",   "message": "İletildi" },
    { "to": "905304445566", "status": "sent",   "message": "İletildi" }
  ]
}

status değeri: success (hepsi iletildi), partial (bir kısmı iletildi), failed (hiçbiri iletilmedi). İletilemeyen mesajların kredisi otomatik iade edilir. Geçersiz numaralar invalid dizisinde döner ve ücretlendirilmez.

GET Bakiye

https://toplusms.fun/api/v1/balance.php

curl "https://toplusms.fun/api/v1/balance.php" -H "Authorization: Bearer tsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "status": "success", "username": "firmam", "credits": 4820 }

GET Kampanya listesi

https://toplusms.fun/api/v1/campaigns.php?limit=20&page=1 · limit en fazla 50.

{
  "status": "success", "page": 1, "limit": 20, "total": 37,
  "campaigns": [
    { "id": 1042, "title": "Kargo bildirimi", "sender": "TOPLUSMS",
      "total": 2, "sent": 2, "failed": 0, "cost": 2, "created_at": "2026-10-22 14:05:11" }
  ]
}

GET Kampanya detayı

https://toplusms.fun/api/v1/campaign.php?id=1042

{
  "status": "success",
  "campaign": { "id": 1042, "title": "Kargo bildirimi", "message": "Merhaba…", "segments": 1,
                "total": 2, "sent": 2, "failed": 0, "cost": 2, "created_at": "2026-10-22 14:05:11" },
  "results": [ { "to": "905301112233", "status": "sent", "message": "İletildi" } ]
}

Kredi hesabı

Harcanan kredi = mesaj parça sayısı × alıcı sayısı. Türkçe karakter (ç, ğ, ı, ö, ş, ü) içermeyen mesajda bir parça 160, Türkçe karakter içerenlerde 70 karakterdir. Uzun mesajlar parçalanır (153 / 67 karakter). İletilemeyen alıcıların kredisi iade edilir. Krediyi Paket Satın Al sayfasından yükleyebilirsiniz.

Hata kodları

Hatalarda HTTP durum kodu ve şu biçimde bir JSON döner:

{ "status": "error", "code": "insufficient_credits", "message": "Yetersiz kredi.", "required": 12, "balance": 5 }
HTTPcodeAnlamı
400invalid_jsonİstek gövdesi geçerli JSON değil.
401missing_api_key · invalid_api_keyAnahtar gönderilmedi ya da geçersiz/iptal edilmiş.
402insufficient_creditsKrediniz yetersiz. required ve balance alanları döner.
403account_suspended · ip_not_allowedHesap askıda ya da istek izinli IP listesi dışından geldi.
404not_foundKampanya bulunamadı.
405method_not_allowedYanlış HTTP yöntemi (Allow başlığına bakın).
422invalid_message · message_too_long · invalid_recipients · too_many_recipients · invalid_idGönderilen alanlar geçersiz.
429rate_limited · too_many_attemptsHız sınırı aşıldı; Retry-After saniye sonra tekrar deneyin.
500server_errorBeklenmeyen hata. Kısa süre sonra tekrar deneyin.

İpuçları