πSMS API Dokumantasyonu

Kendi uygulamanizdan dogrudan SMS gonderin, numara dogrulama ve HLR sorgulari yapin, bakiyenizi programatik olarak goruntuleyin.

Kimlik Dogrulama

Tum isteklerde X-Api-Key header'i ile API anahtarinizi gonderin. Anahtarinizi panelde Hesabim → API Erisimi bolumunden olusturabilirsiniz.

X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Temel Bilgiler

• Base URL: https://<sizin-domaininiz>/api/v1
• Tum istekler POST, Content-Type: application/json ile gonderilir.
• Standart mesaj: 160 karaktere kadar tek segment (coklu segmentte 153/parca). Unicode/ozel karakter: 70 karaktere kadar tek segment (coklu segmentte 67/parca).
• Bir mesaj en fazla 5 segmente bolunebilir.
• Hiz siniri: API anahtari basina dakikada 60 istek.
• Tek istekte en fazla 30 numara.

1. SMS Gonderimi

POST /api/v1/sms/send

Alan	Zorunlu	Aciklama
from	Evet	Gonderici adi (alfanumerikse ≤11, sayisalsa ≤15 karakter)
to	Evet	Alici numara(lar), virgulle ayrilmis
text	Evet	Mesaj icerigi
type	Hayir	"0" standart / "1" Unicode; belirtilmezse otomatik
scheduled	Hayir	ISO 8601 ileri tarih (orn: 2026-03-15T10:00:00Z)

curl -X POST "https://<sizin-domaininiz>/api/v1/sms/send" \
  -H "X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "FirmaAdi",
    "to": "905321234567",
    "text": "Merhaba, siparisiniz kargoya verildi."
  }'

Yanit (tekli gonderim):

{
  "status": "OK",
  "messageId": "128",
  "results": [
    { "to": "905321234567", "messageId": "128", "status": "sent" }
  ]
}

messageId yalnizca tekli gonderimde ust seviyede de yer alir; toplu gonderimde her numaranin kendi messageId'si results dizisinden okunmalidir. Bu ID, webhook bildirimlerindeki messageId ile birebir eslesir.

PHP Ornegi

<?php
$ch = curl_init('https://<sizin-domaininiz>/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'FirmaAdi',
        'to' => '905321234567',
        'text' => 'Merhaba, siparisiniz kargoya verildi.',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Python Ornegi

import requests

response = requests.post(
    "https://<sizin-domaininiz>/api/v1/sms/send",
    headers={"X-Api-Key": "pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "from": "FirmaAdi",
        "to": "905321234567",
        "text": "Merhaba, siparisiniz kargoya verildi.",
    },
)
print(response.json())

2. Bakiye Sorgulama

POST /api/v1/sms/balance — istek govdesi yok.

curl -X POST "https://<sizin-domaininiz>/api/v1/sms/balance" \
  -H "X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "status": "OK", "balance": 245.50 }

3. HLR Sorgulama

POST /api/v1/hlr/query — numaranin anlik ulasilabilirligini, operatorunu ve roaming/tasima bilgisini doner.

curl -X POST "https://<sizin-domaininiz>/api/v1/hlr/query" \
  -H "X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"number": "905321234567"}'

{
  "status": "OK",
  "results": [
    { "number": "905321234567", "reachable": true, "country": "Turkey", "operator": "Turkcell", "roaming": false, "ported": false }
  ]
}

4. Numara Dogrulama

POST /api/v1/nv/query — numaranin gercekten var olan bir hat olup olmadigini kontrol eder.

curl -X POST "https://<sizin-domaininiz>/api/v1/nv/query" \
  -H "X-Api-Key: pisms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"number": "905321234567"}'

{
  "status": "OK",
  "results": [
    { "number": "905321234567", "valid": true, "country": "Turkey", "type": "MOBILE" }
  ]
}

Hata Kodlari

{ "error": "insufficient_credit", "description": "Yetersiz kredi." }

Kod	HTTP	Aciklama
unauthorized	401	X-Api-Key eksik veya gecersiz
account_inactive	403	Hesabiniz aktif degil
invalid_request	400	Zorunlu alan eksik / gecersiz JSON
invalid_sender	400	Gonderici adi kurallara uymuyor
invalid_recipients	400	Gecerli numara bulunamadi
too_many_recipients	400	30'dan fazla numara
message_too_long	400	Mesaj 5 segmentten uzun
invalid_scheduled_time	400	Gecersiz/gecmis zamanlama
insufficient_credit	402	Yetersiz bakiye
rate_limited	429	Dakikalik istek siniri asildi
method_not_allowed	405	POST disinda bir metot
service_unavailable	503	Servis gecici olarak yanit veremiyor

Toplu gonderimde numara bazinda results dizisi icinde ayrica su degerler donebilir: invalid_number, provider_error, ambiguous, not_attempted, send_failed.

Webhook (Teslim Bildirimleri)

Gonderdiginiz SMS'lerin teslim durumu degistiginde kendi sunucunuza otomatik bildirim gonderebiliriz.

Kurulum

1. Panelde Hesabim → API Erisimi → Webhook URL alanina kendi bildirim adresinizi girin.
2. Bu adres POST isteklerini JSON govde ile kabul etmeli ve HTTP 200 donmelidir.

Payload Formati

{
  "messageId": "128",
  "to": "905321234567",
  "status": "delivered",
  "timestamp": "2026-07-10T12:00:00Z"
}

status: delivered, undelivered veya expired olabilir. messageId, gonderim yanitinda aldiginiz kimlikle birebir eslesir.

Sunucunuz HTTP 200 disinda yanit doner veya zaman asimina ugrarsa, bildirim en fazla 3 kez araliklarla yeniden denenir.

Destek

Sorulariniz icin Iletisim sayfasindan bize ulasabilirsiniz.