Novpix Vatan SMS

Novpix firması tarafından geliştirilen Vatan SMS API entegrasyon paketi. SMS gönderme, bakiye sorgulama ve teslimat raporu alma işlemlerini kolaylaştırır.

🚀 Kurulum

npm install novpix-vatan-sms

📖 Kullanım

Temel Kurulum

const { VatanSMS } = require('novpix-vatan-sms');

const sms = new VatanSMS({
  userCode: 'your-user-code',
  username: 'your-username', 
  password: 'your-password',
  sender: 'your-sender-name'
});

TypeScript ile Kullanım

import { VatanSMS, SMSMessage } from 'novpix-vatan-sms';

const sms = new VatanSMS({
  userCode: 'your-user-code',
  username: 'your-username',
  password: 'your-password', 
  sender: 'your-sender-name',
  timeout: 30000 // opsiyonel
});

SMS Gönderme

Tek SMS Gönderme

const message = {
  numbers: '5551234567', // Türkiye formatında (başında 0 veya +90 olmadan)
  message: 'Merhaba! Bu bir test mesajıdır.',
  msgheader: 'VATANSMS', // opsiyonel (varsayılan: constructor'daki sender)
  filter: '0', // opsiyonel: '0' normal, '1' flash SMS
  tur: 'Turkce' // opsiyonel: 'Normal' veya 'Turkce' (Türkçe karakter desteği)
};

const result = await sms.sendSMS(message);

if (result.success) {
  console.log('SMS gönderildi! Sonuç:', result.result);
} else {
  console.error('Hata:', result.error);
}

Türkçe Karakter Desteği ile SMS

const message = {
  numbers: '5551234567',
  message: 'Merhaba! Türkçe karakterler: ğüşıöç ĞÜŞIÖÇ',
  tur: 'Turkce' // Türkçe karakter desteği aktif
};

const result = await sms.sendSMS(message);

Çoklu Numara SMS Gönderme

const message = {
  numbers: ['5551234567', '5559876543'], // Birden fazla numara
  message: 'Toplu SMS mesajı',
};

const result = await sms.sendSMS(message);

Toplu SMS Gönderme (Farklı Mesajlar)

const messages = [
  {
    numbers: '5551234567',
    message: 'İlk mesaj'
  },
  {
    numbers: '5559876543', 
    message: 'İkinci mesaj'
  }
];

const results = await sms.sendBulkSMS(messages);
results.forEach((result, index) => {
  if (result.success) {
    console.log(`Mesaj ${index + 1} gönderildi:`, result.result);
  } else {
    console.error(`Mesaj ${index + 1} hatası:`, result.error);
  }
});

Bakiye Sorgulama

const balance = await sms.getBalance();

if (balance.success) {
  console.log(`Bakiye: ${balance.balance} TL`);
  console.log('Detaylı bilgi:', balance.data);
} else {
  console.error('Bakiye sorgulanamadı:', balance.error);
}

SMS Takip (Özel Kod ile)

// SMS gönderimi sonrası alınan özel kod ile takip
const trackResult = await sms.trackSMS('448141074'); // Örnek özel kod

if (trackResult.success) {
  console.log('SMS durumu:', trackResult.data);
} else {
  console.error('SMS takip hatası:', trackResult.error);
}

Telefon Numarası Yardımcı Fonksiyonları

// Telefon numarasını formatla (Vatan SMS formatına çevirir)
const formatted = VatanSMS.formatPhoneNumber('0555 123 45 67');
console.log(formatted); // 5551234567

// Telefon numarası geçerliliğini kontrol et
const isValid = VatanSMS.isValidPhoneNumber('0555 123 45 67');
console.log(isValid); // true

// Farklı formatlar
console.log(VatanSMS.formatPhoneNumber('+90 555 123 45 67')); // 5551234567
console.log(VatanSMS.formatPhoneNumber('905551234567')); // 5551234567
console.log(VatanSMS.formatPhoneNumber('555-123-45-67')); // 5551234567

🔧 Konfigürasyon Seçenekleri

interface VatanSMSConfig {
  userCode: string;      // Kullanıcı kodunuz (zorunlu)
  username: string;      // Kullanıcı adınız (zorunlu)
  password: string;      // Şifreniz (zorunlu)
  sender: string;        // Gönderici adınız (zorunlu)
  baseUrl?: string;      // API base URL (varsayılan: http://panel.vatansms.com/panel)
  timeout?: number;      // İstek timeout süresi ms (varsayılan: 30000)
}

📝 API Referansı

VatanSMS Sınıfı

sendSMS(message: SMSMessage): Promise<SMSResponse>

SMS mesajı gönderir (tek veya çoklu numara).

sendBulkSMS(messages: SMSMessage[]): Promise<SMSResponse[]>

Birden fazla farklı SMS mesajı gönderir.

getBalance(): Promise<BalanceResponse>

Hesap bakiyesini sorgular.

trackSMS(ozelkod: string): Promise<any>

SMS durumunu özel kod ile sorgular.

static formatPhoneNumber(phone: string): string

Telefon numarasını Vatan SMS formatına çevirir (5XXXXXXXXX).

static isValidPhoneNumber(phone: string): boolean

Telefon numarasının geçerliliğini kontrol eder.

Tip Tanımları

interface SMSMessage {
  message: string;           // Mesaj içeriği
  numbers: string | string[]; // Alıcı numara(lar) - 5XXXXXXXXX formatında
  msgheader?: string;        // Gönderici adı (opsiyonel)
  filter?: '0' | '1';       // '0': Normal SMS, '1': Flash SMS
  tur?: 'Normal' | 'Turkce'; // SMS tipi: 'Normal' veya 'Turkce' (Türkçe karakter desteği)
}

interface SMSResponse {
  success: boolean;
  result?: string;          // API'den dönen sonuç
  error?: string;
  data?: any;
}

interface BalanceResponse {
  success: boolean;
  balance?: number;         // Bakiye miktarı
  error?: string;
}

🛠️ Geliştirme

# Projeyi klonla
git clone https://github.com/Novpix/novpix-vatan-sms.git
cd novpix-vatan-sms

# Bağımlılıkları yükle
npm install

# TypeScript'i derle
npm run build

# Geliştirme modunda çalıştır
npm run dev

# Testleri çalıştır
npm test

# Manuel test (gerçek API ile)
npm run test:manual

🧪 Test Script'i

Paket kendi dizininde test.js dosyası içerir:

# Environment variables ayarlayın:
export USER_CODE="your-user-code"
export USERNAME="your-username"  
export PASSWORD="your-password"
export SENDER="your-sender"
export TEST_PHONE="5XXXXXXXXX"

# Test çalıştırın:
npm run test:manual

📄 Lisans

MIT License - Detaylar için LICENSE dosyasına bakın.

🤝 Katkıda Bulunma

1. Bu projeyi fork edin
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add some amazing feature')
4. Branch'inizi push edin (git push origin feature/amazing-feature)
5. Pull Request oluşturun

⚠️ Önemli Notlar

• Bu paket Novpix firması tarafından geliştirilmiştir ve resmi Vatan SMS paketi değildir
• API endpoint'leri Vatan SMS API dokümantasyonuna göre oluşturulmuştur
• Gerçek kullanım için Vatan SMS hesabınızdan API bilgilerinizi alın
• Production ortamında kullanmadan önce kapsamlı testler yapın
• Telefon numaraları 5XXXXXXXXX formatında olmalıdır (başında 0 veya +90 olmadan)

🚨 Çalışmayan API Endpoint'leri

Vatan SMS'in kendi dokümantasyonunda belirtilen bazı endpoint'ler 404 Not Found hatası vermektedir:

• ❌ smstakipeski.php - Tarihli SMS takip (dokümantasyonda var, fakat çalışmıyor)
• ❌ orjinatorliste.php - Orjinatör listesi (dokümantasyonda var, fakat çalışmıyor)

✅ Çalışan API Endpoint'leri

• ✅ smsgonder1N.php - SMS gönderme
• ✅ kullanicibilgi.php - Bakiye sorgulama
• ✅ smstakip.php - SMS takip (özel kod ile)

📞 Destek

Sorularınız için GitHub Issues kullanabilirsiniz.