Bu doküman gönderim yetkisi verir mi?
Hayır. Buradaki YOUR_API_KEY ve diğer örnek alanlar gerçek bir anahtar değildir. İstek gönderebilmek için yetkili kurumun aktif API anahtarı, aktif hesabı, onaylı başlığı ve yeterli kontörü gerekir. Anahtarsız veya geçersiz anahtarlı istekler reddedilir.
API anahtarlarını kurum yöneticisi yönetir. Anahtarı sunucunuzda saklayın, izinli IP ve günlük/aylık limitleri ihtiyacınıza göre belirleyin. Anahtarın açığa çıktığından şüphelenirseniz iptal edip yenisini oluşturun; gerçek anahtarı web sayfasına, e-postaya veya destek mesajına yapıştırmayın.
Başlamadan önce
Aktif kurum hesabı, kullanılabilir kontör, onaylı gönderici başlığı ve aktif API anahtarı gerekir. Aşağıdaki örnekler şemayı gösterir; çalıştırıldığında gerçek alıcıya gönderim oluşturabilecek POST isteklerini yalnızca yetkili test alıcınızla kullanın. YOUR_API_KEY ve YOUR_TEST_PHONE değerleri örnek yer tutuculardır.
API anahtarını tarayıcıya veya mobil uygulamanın kaynak koduna koymayın. İstekleri kendi sunucunuzdan gönderin; anahtarı ortam değişkeninde saklayın.
Onaylı canlı demo
Canlı SMS demosu için /demo sayfasından başvurun. Talep hemen hesap veya gönderim yetkisi açmaz; önce Pınar SMS sizinle görüşür, ardından yönetici kişisel davet bağlantınızı paylaşır. Şifrenizi belirleyip kayıtlı cep telefonunuzu doğruladıktan sonra paneli ve API’yi deneyebilirsiniz.
Demo SMS’leri yalnızca YENER PINAR başlığıyla, doğruladığınız kendi cep telefonuna gönderilir. Gerçek kullanıma geçtiğinizde, gerekli belge ve onay işlemlerinin ardından kurumunuza ait, tercih ettiğiniz gönderici başlığıyla SMS gönderebilirsiniz. Demo API anahtarı kişiseldir; panel ve API aynı test hakkını kullanır. Anahtarınızı yalnızca demo ekranından oluşturun. Demo bakiyesi ve raporları yalnızca size ait test kapsamını gösterir.
Kimlik doğrulama ve bakiye
Authorization: Bearer başlığı tüm bu uç noktalar için gereklidir. API anahtarına IP kısıtlaması tanımlandıysa sunucunuzun çıkış IP’si izinli olmalıdır. Bakiye yanıtındaki balance gerçek kurum hesabında kurumun mevcut kontörünü, kişisel demo anahtarında yalnızca kalan demo hakkını gösterir.
curl "https://xn--pnarsms-rfb.com/api/v1/balance" \
-H "Authorization: Bearer YOUR_API_KEY"Onaylı gönderici başlıkları
GET /api/v1/sender-titles kuruma ait ve anahtarın kullanabildiği başlıkları listeler. sender alanına burada izin verilen başlığı yazın. Başlığın ekranda görünmesi ile gönderim yetkisinin bulunması ayrı kontrollerdir.
curl "https://xn--pnarsms-rfb.com/api/v1/sender-titles" \
-H "Authorization: Bearer YOUR_API_KEY"Tek alıcıya SMS gönderimi
POST /api/v1/sms/send isteğinde sender, to ve message zorunludur. Mesaj 1–1000 karakter, external_id en fazla 120 karakter olabilir. Başarılı ilk yanıt HTTP 202’dir; message_id, campaign_id, status, credit_used ve remaining_balance alanlarını saklayın. 202 teslim edildi anlamına gelmez.
curl -X POST "https://xn--pnarsms-rfb.com/api/v1/sms/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reminder-2026-001" \
-d '{"sender":"YOUR_APPROVED_TITLE","to":"YOUR_TEST_PHONE","message":"Yetkili test mesaji","external_id":"reminder-2026-001"}'Toplu gönderim ve limitler
POST /api/v1/sms/bulk-send aynı metni recipients dizisindeki alıcılara gönderir. Bir istekte 1–1000 numara kabul edilir. Mesaj en fazla 1000 karakterdir. Yanıtta campaign_id, message_ids, recipient_count ve credit_used bulunur. Günlük/aylık anahtar limitleri ile istek hız sınırını kendi iş kuyruğunuzda dikkate alın.
Idempotency-Key ile güvenli tekrar deneme
Aynı iş için aynı anahtarı kullanın. Başlık verilmediyse external_id referans olarak kullanılır; başlık varsa önceliklidir. Başarılı gönderimin yanıtı kaybolduğunda aynı kurum, API anahtarı ve uç nokta kapsamında referansı koruyarak yeniden deneyin. Aynı anahtarı farklı alıcı veya metin için kullanmayın; yeni iş için yeni bir referans üretin. Bu mekanizmayı sınırsız süreli, bütün eşzamanlı durumlarda kesin tek gönderim garantisi olarak yorumlamayın.
Teslim raporunu sorgulayın
Tek mesaj için GET /api/v1/sms/report/{message_id}; kampanya özeti için GET /api/v1/campaigns/{campaign_id}/report kullanılır. Yanıt kimliklerini kendi veritabanınızda iş kaydıyla eşleştirin. Kampanya raporundaki queued, sent, delivered, failed ve credit_used alanları süreci takip etmenizi sağlar.
curl "https://xn--pnarsms-rfb.com/api/v1/sms/report/YOUR_MESSAGE_ID" \
-H "Authorization: Bearer YOUR_API_KEY"Hata yanıtlarını nasıl ele almalısınız?
Uygulama hataları success: false, error_code ve message ile döner. Alan doğrulama hataları HTTP 422 ve detail içerebilir; genel hız sınırı HTTP 429 döndürebilir. Her hata yanıtının aynı gövde biçiminde olduğunu varsaymayın.
- 401 INVALID_API_KEY: anahtarı kontrol edin.
- 403 API_KEY_DISABLED, IP_NOT_ALLOWED veya ORGANIZATION_NOT_ACTIVE: kurum ve erişim ayarlarını kontrol edin.
- 400 INVALID_SENDER_TITLE, INVALID_PHONE_NUMBER veya RECIPIENT_OPTED_OUT: ilgili veriyi düzeltin; körlemesine tekrar göndermeyin.
- 402 INSUFFICIENT_BALANCE: kontör durumunu kontrol edin.
- 429: hız veya kullanım limiti; varsa Retry-After bilgisini dikkate alın ve kontrollü bekleme uygulayın.
- 404 MESSAGE_NOT_FOUND veya CAMPAIGN_NOT_FOUND: kimliğin doğru kuruma ait olduğunu kontrol edin.