VOIS SMS API

Kendi yazılımınızdan SMS, OTP ve MMS gönderin; gönderimlerinizin durumunu, bakiyenizi ve gönderen başlıklarınızı sorgulayın. Tüm servisler HTTPS üzerinden JSON ile çalışır.

Temel adreshttps://api.vois.com.tr

Genel bilgiler

Bütün servisler için geçerli kurallar.

İstekler HTTPS ile, aşağıda belirtilen temel adres üzerine yapılır. Örneğin tekil SMS için tam adres: https://api.vois.com.tr/sms/create
POST isteklerinde gövde JSON olmalı ve Content-Type: application/json başlığı gönderilmelidir. Karakter kodlaması UTF-8'dir.
Tarih alanları yyyy-MM-dd HH:mm biçimindedir (ör. 2026-11-10 14:30). Saatler Türkiye saatidir.
Telefon numaralarını ülke koduyla, başında + ve 0 olmadan yazmanızı öneririz: 905321234567.
Sayfalı servislerde pageIndex 0'dan başlar.

Yanıt yapısı

Her yanıt iki alan içerir. İstek başarılıysa data dolu, err null gelir; hatalıysa tersi.

BAŞARILI

{
  "data": { "pkgID": 48213377 },
  "err": null
}

HATALI

{
  "data": null,
  "err": {
    "status": 417,
    "code": "ERR_USER_CREDIT_REQUIRED",
    "message": "ERR_USER_CREDIT_REQUIRED"
  }
}

Alan	Açıklama
data	Servisin döndürdüğü veri. Hata durumunda `null`.
err.status	HTTP durum kodu.
err.code	Hata kodu. Listesi için Hata kodları.
err.message	Hatanın açıklaması. Parametre hatalarında hangi alanın hatalı olduğunu belirtir.

Sistemi korumak için istek sayısı sınırlandırılmıştır. Çok sık istek gönderirseniz 429 yanıtı alırsınız; kısa bir süre bekleyip tekrar deneyin. Toplu gönderimde binlerce numarayı tek tek göndermek yerine çoklu ya da kişiye özel gönderimi kullanın.

Kimlik doğrulama

Her istekte, size verilen API kullanıcı adı ve şifresiyle Basic Authentication başlığı gönderilmelidir.

Kullanıcı adı ve şifre arasına iki nokta koyarak birleştirin: kullanici:sifre
Bu metni Base64 ile kodlayın.
Sonucu Authorization başlığına Basic önekiyle ekleyin.

Örneğin kullanıcı adı smsuser, şifre p4r0la ise smsuser:p4r0la metninin Base64 karşılığı c21zdXNlcjpwNHIwbGE= olur:

HTTP BAŞLIĞI

Authorization: Basic c21zdXNlcjpwNHIwbGE=

Çoğu HTTP kütüphanesi bunu sizin yerinize yapar (cURL'de -u kullanici:sifre, PHP'de CURLOPT_USERPWD, Python'da auth=(...)).

Kullanıcı adı ve şifrenizi yalnızca sunucu tarafındaki kodunuzda saklayın; tarayıcıda çalışan JavaScript'e ya da mobil uygulamaya koymayın. Bilgiler hatalıysa ERR_UNAUTHORIZED_REQUEST hatası döner.

Hızlı başlangıç

Tek bir numaraya SMS gönderen en kısa örnek. KULLANICI, SIFRE ve BASLIK alanlarını kendi bilgilerinizle değiştirin.

curl -X POST https://api.vois.com.tr/sms/create \
  -u 'KULLANICI:SIFRE' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 1,
    "sendingType": 0,
    "title": "Hosgeldin mesaji",
    "content": "Merhaba, kaydiniz tamamlandi.",
    "number": "905321234567",
    "sender": "BASLIK",
    "encoding": 0
  }'

<?php
$body = [
    'type'        => 1,
    'sendingType' => 0,
    'title'       => 'Hosgeldin mesaji',
    'content'     => 'Merhaba, kaydınız tamamlandı.',
    'number'      => '905321234567',
    'sender'      => 'BASLIK',
    'encoding'    => 1, // Türkçe karakter
];

$ch = curl_init('https://api.vois.com.tr/sms/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_USERPWD        => 'KULLANICI:SIFRE',
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($body),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['err'] === null) {
    echo 'Paket no: ' . $res['data']['pkgID'];
} else {
    echo 'Hata: ' . $res['err']['code'];
}

import requests

r = requests.post(
    "https://api.vois.com.tr/sms/create",
    auth=("KULLANICI", "SIFRE"),
    json={
        "type": 1,
        "sendingType": 0,
        "title": "Hosgeldin mesaji",
        "content": "Merhaba, kaydınız tamamlandı.",
        "number": "905321234567",
        "sender": "BASLIK",
        "encoding": 1,
    },
    timeout=30,
)
res = r.json()
if res["err"] is None:
    print("Paket no:", res["data"]["pkgID"])
else:
    print("Hata:", res["err"]["code"])

using System.Net.Http.Headers;
using System.Text;

var http = new HttpClient();
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes("KULLANICI:SIFRE"));
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", token);

var json = """
{
  "type": 1, "sendingType": 0,
  "title": "Hosgeldin mesaji",
  "content": "Merhaba, kaydınız tamamlandı.",
  "number": "905321234567",
  "sender": "BASLIK",
  "encoding": 1
}
""";
var res = await http.PostAsync(
    "https://api.vois.com.tr/sms/create",
    new StringContent(json, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());

const res = await fetch("https://api.vois.com.tr/sms/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Basic " + Buffer.from("KULLANICI:SIFRE").toString("base64"),
  },
  body: JSON.stringify({
    type: 1, sendingType: 0,
    title: "Hosgeldin mesaji",
    content: "Merhaba, kaydınız tamamlandı.",
    number: "905321234567",
    sender: "BASLIK",
    encoding: 1,
  }),
});
const { data, err } = await res.json();
console.log(err ? `Hata: ${err.code}` : `Paket no: ${data.pkgID}`);

Başarılı yanıtta dönen pkgID gönderimin paket numarasıdır; raporları bu numarayla (ya da kendi verdiğiniz customID ile) sorgularsınız.

ParametrelerKodlama, geçerlilik, ileri tarih, ticari ileti Otomatik raporTeslim raporlarını kendi adresinize alın Hata kodlarıDönebilecek tüm hata kodları

Ortak gönderim parametreleri

Tekil, çoklu ve kişiye özel SMS aynı adrese (/sms/create) gönderilir; aralarındaki fark sendingType ve numara alanıdır. Aşağıdaki alanlar üçünde de aynı şekilde kullanılır.

Alan	Açıklama
type int zorunlu	Mesaj tipi. SMS için her zaman `1`.
title string zorunlu	Gönderimi raporlarda tanımanız için paket adı. Alıcıya gitmez. 5–50 karakter.
sender string zorunlu	Gönderen başlığı; alıcının telefonunda gönderen olarak görünür. Hesabınızda onaylı bir başlık olmalıdır (bkz. Gönderen başlıkları).
encoding int opsiyonel	Karakter kodlaması. `0` Standart (varsayılan), `1` Türkçe karakterli, `2` Unicode (emoji vb.). Mesaj boyu ve maliyet buna göre değişir, bkz. Karakter ve mesaj boyu.
validity int opsiyonel	Mesajın operatörde geçerli kalacağı süre, dakika. En az 60, en çok 1440. Varsayılan 1440.
sendingDate string opsiyonel	İleri tarihli gönderim. Biçim `yyyy-MM-dd HH:mm`. Boş bırakılırsa hemen gönderilir. İleri tarihli paket iptal edilebilir.
commercial bool opsiyonel	Ticari ileti (kampanya, tanıtım) ise `true`. Ticari gönderimler İYS kontrolünden geçer; hesabınızda İYS kodu ve marka kodu tanımlı olmalıdır. Bilgilendirme mesajlarında `false`.
skipAhsQuery bool opsiyonel	Gönderimin AHS sorgusuna girmesini istemiyorsanız `true`.
recipientType int opsiyonel	AHS sorgusunda alıcı tipi: `0` Bireysel (varsayılan), `1` Tacir, `2` Her ikisi.
gateway uuid opsiyonel	Aynı başlık için birden fazla ağ geçidi tanımlıysa hangisinden gönderileceği. Değerler Ağ geçitleri servisinden alınır. Çoğu hesapta gerekmez.
customID string opsiyonel	Kendi sisteminizdeki kayıt numarası. Raporları ve iptali bu değerle de yapabilirsiniz. En çok 100 karakter; harf, rakam, `-` ve `.` içerebilir. Her paket için benzersiz olmalıdır, aynı değer tekrar gelirse `ERR_SMS_PKG_CUSTOM_ID_DUPLICATION` döner.
pushSettings.url string opsiyonel	Teslim raporunun otomatik gönderileceği adresiniz. Bkz. Rapor bildirimi.
periodicSettings object opsiyonel	Yalnızca çoklu ve kişiye özel gönderimde. Büyük listeleri parça parça göndermek için: `periodType` her zaman `0`; `interval` iki parça arası dakika (en az 1); `amount` her parçadaki numara sayısı (1000 ve katları).

Aynı içerik aynı numaralara 30 dakika içinde ikinci kez gönderilirse sistem bunu tekrar sayar ve ERR_SMS_PKG_DUPLICATION hatası verir. Bu, hatalı döngülerde çift gönderimi önler.

Tekil SMS

Tek bir numaraya SMS gönderir.

POST/sms/create

Alan	Açıklama
sendingType int zorunlu	Tekil gönderim için `0`.
number string zorunlu	Alıcı numarası.
content string zorunlu	Mesaj metni.
Diğer alanlar: Ortak gönderim parametreleri

İSTEK

{
  "type": 1,
  "sendingType": 0,
  "title": "Randevu hatirlatma",
  "content": "Yarın 10:00 randevunuzu hatırlatırız.",
  "number": "905321234567",
  "sender": "BASLIK",
  "encoding": 1,
  "validity": 1440,
  "commercial": false,
  "customID": "randevu-20261110-0042",
  "pushSettings": { "url": "https://ornek.com/sms-rapor" }
}

YANIT

{
  "data": { "pkgID": 48213377 },
  "err": null
}

Çoklu SMS

Aynı metni birden fazla numaraya tek pakette gönderir.

POST/sms/create

Alan	Açıklama
sendingType int zorunlu	Çoklu gönderim için `1`.
numbers string[] zorunlu	Alıcı numaraları listesi.
content string zorunlu	Herkese gidecek mesaj metni.
Diğer alanlar, `periodicSettings` dahil: Ortak gönderim parametreleri

İSTEK

{
  "type": 1,
  "sendingType": 1,
  "title": "Kasim kampanyasi",
  "content": "Kasım'a özel %20 indirim! Ret için RET yazıp gönderin.",
  "numbers": ["905321234567", "905441234567"],
  "sender": "BASLIK",
  "encoding": 1,
  "commercial": true,
  "sendingDate": "2026-11-15 10:00",
  "periodicSettings": { "periodType": 0, "interval": 5, "amount": 1000 }
}

YANIT

{
  "data": { "pkgID": 48213390 },
  "err": null
}

Bu örnekte liste 15 Kasım 10:00'da başlar ve 5 dakikada bir 1000'er numara gönderilir.

Kişiye özel SMS

Her numaraya farklı metin göndereceğiniz durumlar için (isim, tutar, kod gibi kişiye özel alanlar). Tüm mesajlar tek pakette gider.

POST/sms/create

Alan	Açıklama
sendingType int zorunlu	Kişiye özel gönderim için `2`.
numbers object[] zorunlu	Her alıcı için bir nesne:
nr string	Alıcı numarası.
msg string	Bu numaraya gidecek metin.
xid string opsiyonel	Bu alıcıyı kendi sisteminizde eşleştirmek için numara (en çok 32 karakter, benzersiz olması gerekmez). Numara bazlı raporda geri döner.
Diğer alanlar: Ortak gönderim parametreleri

İSTEK

{
  "type": 1,
  "sendingType": 2,
  "title": "Fatura bildirimi",
  "numbers": [
    { "nr": "905321234567", "msg": "Sayın Ayşe Hanım, 1.250 TL faturanız oluştu.", "xid": "F-1001" },
    { "nr": "905441234567", "msg": "Sayın Mehmet Bey, 980 TL faturanız oluştu.", "xid": "F-1002" }
  ],
  "sender": "BASLIK",
  "encoding": 1,
  "commercial": false
}

YANIT

{
  "data": { "pkgID": 48213402 },
  "err": null
}

OTP SMS

Tek kullanımlık doğrulama kodu gibi, hızlı iletilmesi gereken mesajlar için ayrı ve öncelikli servis. Hesabınızda OTP yetkisi açık olmalıdır; açtırmak için bizimle iletişime geçin.

POST/sms/create-otp

Alan	Açıklama
number string zorunlu	Alıcı numarası.
sender string zorunlu	Gönderen başlığı.
content string zorunlu	Mesaj metni.
encoding int opsiyonel	`0` Standart, `1` Türkçe, `2` Unicode.
validity int opsiyonel	Geçerlilik süresi, dakika. OTP için en az 3, en çok 6; varsayılan 6.
commercial bool opsiyonel	Ticari ileti ise `true`. OTP için genelde `false`.
customID string opsiyonel	Kendi sisteminizdeki kayıt numarası.
trustDate string opsiyonel	SIM kart değişikliği kontrolü için tarih, `yyyy-MM-dd HH:mm:ss`. Bu tarihten sonra numaranın SIM kartı değişmişse mesaj gönderilmez (dolandırıcılığa karşı koruma). Hesabınızda ek yetki gerektirir.
pushSettings.url string opsiyonel	Teslim raporunun gönderileceği adres.

İSTEK

{
  "number": "905321234567",
  "sender": "BASLIK",
  "content": "Doğrulama kodunuz: 482915",
  "encoding": 1,
  "validity": 3,
  "commercial": false,
  "customID": "otp-7731"
}

YANIT

{
  "data": { "pkgID": 48213415 },
  "err": null
}

GET ile gönderim

JSON gönderemeyen eski sistemler için tek satırlık adresle SMS gönderimi. Yeni entegrasyonlarda Tekil SMS servisini öneririz.

GET/direct/?cmd=sendsms&kullanici=…&sifre=…&mesaj=…&gsm=…&baslik=…&nlss=…&ahs=…

Parametre	Açıklama
cmd	Her zaman `sendsms`.
kullanici	API kullanıcı adınız.
sifre	API şifreniz.
mesaj	Mesaj metni (URL kodlamalı).
gsm	Alıcı numarası.
baslik	Gönderen başlığı.
nlss	Kodlama: `0` Standart, `1` Türkçe, `2` Unicode.
ahs	`0` Bilgilendirme (AHS sorgusu yapılmaz), `1` Ticari (AHS sorgusuyla gönderilir).

ÖRNEK

https://api.vois.com.tr/direct/?cmd=sendsms&kullanici=KULLANICI&sifre=SIFRE&mesaj=Merhaba%20d%C3%BCnya&gsm=905321234567&baslik=BASLIK&nlss=1&ahs=0

Yanıt JSON değil, düz metindir: başarılıysa paket numarası, hatalıysa hatanın açıklaması döner.

Bu yöntemde şifre adresin içinde gider ve sunucu loglarında görünebilir. Mümkünse POST servislerini kullanın.

MMS

Görsel içeren mesaj gönderimi.

POST/sms/create

Alan	Açıklama
type int zorunlu	MMS için `4`.
sendingType int zorunlu	`1` (numara listesiyle gönderim).
title string zorunlu	Paket adı, 5–50 karakter.
subject string	MMS konu başlığı.
content string zorunlu	Mesaj metni.
numbers string[] zorunlu	Alıcı numaraları.
sender string zorunlu	Gönderen başlığı.
encoding int opsiyonel	MMS'te varsayılan `2` (Unicode).
media object zorunlu	Gönderilecek dosya:
ext	Dosya uzantısı: `jpg`, `png` …
mimeType	Dosya türü: `image/jpeg`, `image/png` …
data	Dosyanın Base64 ile kodlanmış içeriği.
`validity`, `sendingDate`, `commercial`, `customID`, `periodicSettings`, `pushSettings`: Ortak gönderim parametreleri

İSTEK

{
  "type": 4,
  "sendingType": 1,
  "title": "Yeni sezon katalog",
  "subject": "Yeni sezon",
  "content": "Yeni sezon ürünlerimiz mağazalarda!",
  "numbers": ["905321234567"],
  "sender": "BASLIK",
  "commercial": true,
  "media": {
    "ext": "jpg",
    "mimeType": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQ...(base64)...//2Q=="
  }
}

Yanıt diğer gönderimlerle aynıdır: data.pkgID.

İleri tarihli gönderimi iptal

Henüz gönderim zamanı gelmemiş bir paketi iptal eder. Paket numarası ya da customID ile çalışır; ikisini birlikte göndermeyin.

POST/sms/cancel

Alan	Açıklama
id int	Paket numarası (`pkgID`).
customID string	Gönderimde verdiğiniz kendi numaranız.

İSTEK

{ "id": 48213390 }

YANIT

{
  "data": { "status": 0 },
  "err": null
}

Paket artık değiştirilebilir durumda değilse (gönderim başladıysa) ERR_SMS_PKG_NOT_CHANGEABLE döner.

Paket raporu

Gönderim paketlerinizi tarih aralığına ve filtrelere göre listeler; her paket için toplam, teslim edilen ve edilemeyen sayıları verir.

POST/sms/list

İstek

Alan	Açıklama
startDate string	Başlangıç, `yyyy-MM-dd HH:mm`.
finishDate string	Bitiş, `yyyy-MM-dd HH:mm`.
ids int[] opsiyonel	Belirli paket numaraları.
customIDs string[] opsiyonel	Belirli customID değerleri.
keyword string opsiyonel	Mesaj içeriğinde arama.
sender string opsiyonel	Gönderen başlığına göre filtre.
status int opsiyonel	Paket durumu filtresi, bkz. Paket durum filtreleri.
pageIndex int	Sayfa numarası (0'dan başlar).
pageSize int	Sayfa boyutu, 10–1000.

Yanıt alanları (`data.list[]`)

Alan	Açıklama
id	Paket numarası.
customID	Gönderimde verdiğiniz numara.
type	Mesaj tipi (1 SMS, 4 MMS).
uuid	Paketin benzersiz kimliği.
state	Paket durumu, bkz. Paket durumları.
title / content / senders	Paket adı, mesaj metni ve gönderen başlıkları.
encoding / validity	Kodlama ve geçerlilik süresi.
statistics	`total` toplam mesaj, `rCount` alıcı sayısı, `delivered` teslim edilen, `undelivered` teslim edilemeyen, `credit` harcanan kredi.
isScheduled	Paketin periyodik/zamanlanmış olup olmadığı.
sendingDate / processingDate	Paketin sisteme geldiği ve işleme alındığı zaman.
error	Paket hatası; başarılıysa `null`.

İSTEK

{
  "startDate": "2026-11-01 00:00",
  "finishDate": "2026-11-10 23:59",
  "customIDs": ["randevu-20261110-0042"],
  "pageIndex": 0,
  "pageSize": 50
}

YANIT

{
  "data": {
    "stats": { "totalRecord": 1 },
    "list": [{
      "id": 48213377,
      "customID": "randevu-20261110-0042",
      "type": 1,
      "uuid": "…",
      "state": 6,
      "title": "Randevu hatirlatma",
      "content": "Yarın 10:00 randevunuzu hatırlatırız.",
      "senders": ["BASLIK"],
      "encoding": 1,
      "validity": 1440,
      "statistics": { "total": 1, "credit": 1, "rCount": 1, "delivered": 1, "undelivered": 0 },
      "isScheduled": 0,
      "sendingDate": "2026-11-10T09:12:04",
      "processingDate": "2026-11-10T09:12:05.120000",
      "error": null
    }]
  },
  "err": null
}

Rapor sorgularında günlük bir sınır vardır (ERR_DAILY_REQUEST_LIMIT). Teslim durumunu sık sık sorgulamak yerine rapor bildirimi kullanmanızı öneririz.

Numara bazlı rapor

Bir paketin içindeki her numaranın teslim durumunu verir. Paket numarası ya da customID zorunludur.

POST/sms/list-item

İstek

Alan	Açıklama
pkgID int	Paket numarası. customID gönderilmiyorsa zorunlu.
customID string	Paketin customID değeri. pkgID gönderilmiyorsa zorunlu.
target string opsiyonel	Numara filtresi.
operator int opsiyonel	Operatör filtresi, bkz. Operatörler.
state int opsiyonel	Numara durumu filtresi, bkz. Numara durumları.
pageIndex / pageSize	Sayfalama; pageSize 10–1000.

Yanıt alanları (`data.list[]`)

Alan	Açıklama
id	Kaydın numarası.
target	Mesaj gönderilen numara.
state	Numaranın teslim durumu, bkz. Numara durumları.
setState	Numaranın gönderim aşaması, bkz. Gönderim aşamaları.
operator	Numaranın operatörü.
msg	Kişiye özel gönderimde bu numaraya giden metin; diğerlerinde `null`.
xid	Kişiye özel gönderimde verdiğiniz eşleştirme numarası.
sender / credit	Gönderen başlığı ve harcanan kredi.
error	Bu numaraya ait hata; başarılıysa `null`.
sendingDate / processingDate / deliveryDate	Sisteme geliş, işleme alınma ve operatöre iletilme zamanları.

İSTEK

{
  "pkgID": 48213402,
  "pageIndex": 0,
  "pageSize": 100
}

YANIT

{
  "data": {
    "stats": { "totalRecord": 2 },
    "list": [{
      "id": "…",
      "target": "905321234567",
      "state": 3,
      "setState": 5,
      "operator": 0,
      "msg": "Sayın Ayşe Hanım, 1.250 TL faturanız oluştu.",
      "xid": "F-1001",
      "sender": "BASLIK",
      "credit": 1,
      "error": null,
      "sendingDate": "2026-11-10T09:20:00",
      "processingDate": "2026-11-10T09:20:01",
      "deliveryDate": "2026-11-10T09:20:04"
    }]
  },
  "err": null
}

Özet istatistik

Bir tarih aralığındaki tüm gönderimlerinizin toplamlarını verir.

POST/sms/summary

İSTEK

{
  "startDate": "2026-11-01 00:00",
  "finishDate": "2026-11-30 23:59"
}

YANIT

{
  "data": {
    "total": 1520,
    "delivered": 1488,
    "undelivered": 20,
    "pending": 12,
    "rCount": 1490,
    "credit": 1734
  },
  "err": null
}

Alan	Açıklama
total	Toplam mesaj sayısı.
delivered / undelivered / pending	Teslim edilen, edilemeyen ve sonucu bekleyen mesajlar.
rCount	Toplam alıcı sayısı.
credit	Harcanan kredi.

Numara sorgulama

Belirli bir numaraya geçmişte SMS gönderilip gönderilmediğini ve sonucunu verir. Müşteri "mesaj gelmedi" dediğinde kontrol etmek için kullanışlıdır.

POST/sms/inquiry-number

Alan	Açıklama
gsm string zorunlu	Ülke koduyla tam numara, ör. `905321234567`.
sender string opsiyonel	Yalnızca bu başlıkla yapılan gönderimler.
startDate / finishDate opsiyonel	`yyyy-MM-dd HH:mm`. Verilmezse son 1 ay aranır. Aralık en çok 3 ay olabilir.

İSTEK

{
  "gsm": "905321234567",
  "startDate": "2026-11-01 00:00",
  "finishDate": "2026-11-10 23:59"
}

YANIT

{
  "data": {
    "stats": { "totalRecord": 1 },
    "list": [{
      "pkgID": 48213377,
      "pkgType": 0,
      "sender": "BASLIK",
      "msg": null,
      "state": 3,
      "operator": 0,
      "encoding": 1,
      "validity": 1440,
      "sendingDate": "2026-11-10T09:12:04",
      "deliveryDate": "2026-11-10T09:12:07"
    }]
  },
  "err": null
}

state değerleri için Numara durumları tablosuna bakın.

Rapor bildirimi (push)

Gönderimde pushSettings.url verirseniz, teslim durumları değiştikçe rapor bu adrese POST ile JSON olarak gönderilir. Böylece rapor servislerini sürekli sorgulamanız gerekmez.

Alan	Açıklama
userID	Hesap numaranız.
pkg.id	Paket numarası.
pkg.state	Paket durumu, bkz. Paket durumları.
pkg.statistics	`total` alıcı sayısı, `delivered` iletilen, `undelivered` iletilemeyen.
items[].id	Kaydın numarası.
items[].nr	Numara.
items[].status	Numaranın durumu, bkz. Numara durumları.
items[].lastUpdate	Son güncellenme zamanı.

ADRESİNİZE GELEN İSTEK

{
  "userID": 1042,
  "pkg": {
    "id": 48213377,
    "state": 6,
    "statistics": { "total": 1, "delivered": 1, "undelivered": 0 }
  },
  "items": [
    { "id": "…", "nr": "905321234567", "status": 3, "lastUpdate": "2026-11-10T09:12:07.000Z" }
  ]
}

Bildirim adresiniz internetten erişilebilir, HTTPS ve 200 dönen bir adres olmalıdır. Aynı paket için birden fazla bildirim gelebilir; kayıtlarınızı pkg.id ve items[].nr ile güncelleyin.

Bakiye

Hesabınızdaki kalan krediyi verir.

GET/user/credit

İSTEK

curl https://api.vois.com.tr/user/credit \
  -u 'KULLANICI:SIFRE'

YANIT

{
  "data": { "credit": 25400 },
  "err": null
}

Gönderen başlıkları

Hesabınıza tanımlı gönderen başlıklarını ve onay durumlarını listeler. Yalnızca onaylı (status: 1) başlıklarla gönderim yapılabilir.

POST/sms/list-sender

Alan	Açıklama
keyword opsiyonel	Başlık adında arama.
status opsiyonel	Duruma göre filtre, bkz. Başlık durumları.
pageIndex / pageSize	Sayfalama; pageSize 10–100.

İSTEK

{ "pageIndex": 0, "pageSize": 10 }

YANIT

{
  "data": {
    "stats": { "totalRecord": 1 },
    "list": [{
      "uuid": "…",
      "title": "BASLIK",
      "status": 1,
      "gateways": ["…"]
    }]
  },
  "err": null
}

Yeni başlık açtırmak için bizimle iletişime geçin.

Ağ geçitleri

Hesabınıza tanımlı ağ geçitlerini listeler. Aynı başlık için birden fazla ağ geçidi varsa, buradaki uuid değerini gönderimde gateway alanına yazarak gönderimin hangi geçitten yapılacağını seçebilirsiniz. Çoğu hesapta gerekmez.

GET/sms/list-gateway

Alan	Açıklama
uuid	Ağ geçidinin kimliği.
smsType	Ağ geçidinin SMS tipi.
operator	Operatör, bkz. Operatörler.
isOTP	OTP gönderimine uygun olup olmadığı.
simChangeControl	SIM değişikliği kontrolü yapılabilip yapılamayacağı.
senders	Bu geçide bağlı gönderen başlıkları.

YANIT

{
  "data": {
    "stats": { "totalRecord": 1 },
    "list": [{
      "uuid": "d50fd82f-c578-4965-b4c4-1124ed5509da",
      "smsType": 0,
      "operator": 0,
      "isOTP": false,
      "simChangeControl": false,
      "senders": ["BASLIK"]
    }]
  },
  "err": null
}

Gelen SMS (MO)

Alıcıların kısa numaranıza gönderdiği mesajları (ör. "RET" yazarak ticari iletiden çıkma istekleri) listeler. Hesabınızda kısa numara tanımlı olmalıdır.

POST/mo/list-request

Alan	Açıklama
keyword	Anahtar kelime (ör. `RET`).
startDate / finishDate	`yyyy-MM-dd HH:mm`.
pageIndex / pageSize	Sayfalama; pageSize 10–1000.
Yanıt (data.list[])
gsm	Mesajı gönderen numara.
msg	Gelen mesaj metni.
keyword	Eşleşen anahtar kelime.
state	Durum, bkz. MO durumları.
network	Gönderenin operatörü.
shortNr	Mesajın geldiği kısa numara.
processInfo.create.date	Mesajın sisteme geldiği zaman.

İSTEK

{
  "keyword": "RET",
  "startDate": "2026-11-01 00:00",
  "finishDate": "2026-11-10 23:59",
  "pageIndex": 0,
  "pageSize": 100
}

MO kısa numarası tanımlı değilse ERR_MO_NOT_FOUND döner.

Karakter ve mesaj boyu

Uzun mesajlar birden fazla SMS olarak gönderilir ve her parça ayrı ücretlendirilir. Bir mesajın kaç SMS sayılacağı kodlamaya göre değişir.

Mesaj boyu	Standart (`0`)	Türkçe (`1`)	Unicode (`2`)
1 SMS	0–155	0–150	0–65
2 SMS	156–301	151–293	66–129
3 SMS	302–454	294–442	130–196
4 SMS	455–607	443–591	197–263
5 SMS	608–760	592–740	264–330
6 SMS	761–913	741–889	331–397

Standart kodlamada Türkçe karakterler (ç, ğ, ı, ö, ş, ü) desteklenmez. Türkçe karakter kullanıyorsanız 1, emoji ya da başka alfabeler kullanıyorsanız 2 seçin. Unicode mesajlar çok daha erken bölünür.

Durum kodları

Paket durumları (state)

Kod	Anlamı
-4	İptal edildi
-3	Gönderim başarısız oldu
-2	Paket oluşturulamadı
-1	Operatör tarafından reddedildi
0	Kaydediliyor
1	Beklemede
2	Kuyruğa alınıyor
3	Gönderiliyor
4	Gönderildi
5	Kısmen raporlandı
6	Tamamlandı

Numara durumları (state / status)

Kod	Anlamı
-2	İptal edildi
-1	Operatör tarafından reddedildi
0	Beklemede
1	Gönderiliyor
2	Gönderildi (operatöre iletildi)
3	Numaraya iletildi
4	Numaraya iletilemedi
5	Zaman aşımı (geçerlilik süresinde iletilemedi)

Paket durum filtreleri (rapor: status)

Kod	Anlamı
0	Tüm mesajlar
1	Kuyrukta
2	İşlemde
3	İleri tarihli
4	Periyodik
5	Tamamlanmış
6	İptal
7	Başarısız

Gönderim aşamaları (setState)

Kod	Anlamı
0	Beklemede
1	Gönderiliyor
2	Gönderildi
3	Raporlanıyor
5	Bitti

Başlık durumları (sender status)

Kod	Anlamı
0	Beklemede
1	Onaylandı
2	Reddedildi
3	Yasaklı

MO durumları

Kod	Anlamı
-2	Başarısız
-1	Eşleşme yok
0	Beklemede
1	İşleniyor
2	Tamamlandı

Operatörler

Kod	Operatör
0	Turkcell
1	Vodafone
2	Türk Telekom (Avea)
3	NetGSM

Hata kodları

Hatalı isteklerde err.code alanında aşağıdaki kodlardan biri döner.

Kod	HTTP	Anlamı ve yapılacak
ERR_BAD_REQUEST	400	İstek hatalı ya da eksik. Gövdeyi ve zorunlu alanları kontrol edin.
ERR_INVALID_PARAM	417	Bir parametre geçersiz; hangisi olduğu `message` alanında yazar.
ERR_UNAUTHORIZED_REQUEST	403	Kullanıcı adı veya şifre hatalı, hesapta IP kısıtı var ya da API yetkisi açık değil.
ERR_USER_NOT_AUTHORIZED	401	Hesabınızın bu işlem için yetkisi yok (ör. OTP yetkisi kapalı).
ERR_INVALID_SMS_SENDER	417	Gönderen başlığı hatalı ya da onaylı değil.
ERR_EMPTY_SMS_PACKAGE	417	Pakette gönderilebilecek geçerli numara kalmadı: numaralar hatalı biçimde, kara listede ya da ticari iletide İYS onayı yok.
ERR_INVALID_SMS_SENDING_DATE	417	Gönderim tarihi geçersiz ya da geçmişte.
ERR_USER_CREDIT_REQUIRED	417	Yeterli krediniz yok.
ERR_PARENT_USER_CREDIT_REQUIRED	417	Bağlı olduğunuz ana hesapta yeterli kredi yok. Bizimle iletişime geçin.
ERR_USER_BRAND_CODE_NOT_FOUND	417	Ticari gönderim için İYS marka kodunuz tanımlı değil.
ERR_USER_IYS_SETTINGS_NOT_FOUND	400	Hesabınızda İYS tanımları yok.
ERR_SMS_PKG_CUSTOM_ID_DUPLICATION	400	Bu customID ile daha önce paket oluşturulmuş.
ERR_SMS_PKG_DUPLICATION	417	Aynı mesaj bu numaralara son 30 dakika içinde zaten gönderildi.
ERR_INVALID_DATE_RANGE	400	Tarih aralığı geçersiz.
ERR_SMS_PKG_NOT_FOUND	400	Paket bulunamadı.
ERR_SMS_PKG_NOT_CHANGEABLE	400	Paket bu aşamada değiştirilemez/iptal edilemez.
ERR_SMS_PKG_CREATING_FAILED	417	Paket oluşturulamadı. Tekrar deneyin; sürerse bize bildirin.
ERR_INVALID_PRICING_PLAN	400	Hesabınızın fiyat planı geçersiz. Bizimle iletişime geçin.
ERR_CREDIT_PLAN_NOT_FOUND	400	Kredi planı bulunamadı. Bizimle iletişime geçin.
ERR_USER_NOT_FOUND	417	Kullanıcı bulunamadı.
ERR_MO_NOT_FOUND	400	Hesabınızda MO kısa numarası tanımlı değil.
ERR_DAILY_REQUEST_LIMIT	403	Günlük rapor sorgulama sınırı aşıldı.
ERR_CONCURRENT_REQUEST_LIMIT	400	Aynı anda çok fazla istek gönderildi; istekleri sıraya koyun.
ERR_NOT_FOUND	404	İstek yapılan adres hatalı.
ERR_SYSTEM_MAINTENANCE	503	Sistem bakımda; bir süre sonra tekrar deneyin.
ERR_INTERNAL_SERVER	500	Sunucu hatası; tekrar deneyin, sürerse bize bildirin.
ERR_RATE_LIMIT	429	Saniyedeki istek sınırı aşıldı; kısa bir süre bekleyip tekrar deneyin.
ERR_SERVICE_UNAVAILABLE	502	SMS servisine geçici olarak ulaşılamıyor; birkaç dakika sonra tekrar deneyin.

Genel bilgiler

Yanıt yapısı

Kimlik doğrulama

Hızlı başlangıç

Ortak gönderim parametreleri

Tekil SMS

Çoklu SMS

Kişiye özel SMS

OTP SMS

GET ile gönderim

MMS

İleri tarihli gönderimi iptal

Paket raporu

İstek

Yanıt alanları (data.list[])

Numara bazlı rapor

İstek

Yanıt alanları (data.list[])

Özet istatistik

Numara sorgulama

Rapor bildirimi (push)

Bakiye

Gönderen başlıkları

Ağ geçitleri

Gelen SMS (MO)

Karakter ve mesaj boyu

Durum kodları

Paket durumları (state)

Numara durumları (state / status)

Paket durum filtreleri (rapor: status)

Gönderim aşamaları (setState)

Başlık durumları (sender status)

MO durumları

Operatörler

Hata kodları

Yanıt alanları (`data.list[]`)

Yanıt alanları (`data.list[]`)