Ana içeriğe geç

Template ile SMS gönderme

POST 
/send/template

İstek: POST https://ext-api.netgsm.com.tr/sms/v3/send/template
Canlı ortam: https://ext-api.netgsm.com.tr/sms/v3

Kayıtlı template'leri verilen parametrelerle doldurup gönderen bir görev oluşturur. Her kayıt bir template, template'in parametreleri ve bir alıcıdır. Kullanılabilecek template'ler hesabın kendi template'leri ve herkese açık template'lerdir; kimlikleri ve parametreleri GET /templates ile listelenir. Doldurulan metinler /send'e verilmiş gibi işlenir ve yanıt /send yanıtıyla aynıdır.

Toplu doğrulama. Bir istekte en fazla 20 kayıt bulunur. /send'den farklı olarak template ile ilgili hatalar isteğin tamamını reddeder ve hiçbir şey gönderilmez: eksik ya da geçersiz bir templateId veya recipient, hesabın kullanamadığı bir template ya da template'e uymayan parametreler 400 döndürür. Template'ler doldurulduktan sonra kayıtlar /send'deki gibi tek tek değerlendirilir (alıcı biçimi, metin uzunluğu, mükerrer alıcı). Hatalı kayıtlar rejectedItems içinde templates dizisindeki konumlarıyla (index) bildirilir.

İstek sınırı. Hesap başına dakikada 1000 istek, /send sınırından ayrı. Pencere ilk istekle başlar ve sabittir; reddedilen istekler de sayılır. Aşıldığında 429 Retry-After başlığıyla döner.

Yeniden deneme. /send ile aynıdır: aynı istek iki kez gönderilirse iki görev oluşur. 503 çoğunlukla hiçbir şeyin kuyruğa alınmadığını gösterir. Körlemesine yeniden göndermeden önce GET /report ile kontrol edebilirsiniz.

Request​

Bodyrequired

    senderstringrequired

    Gönderici başlığı. Hesaba kayıtlı bir başlıkla yazıldığı gibi birebir eşleşmelidir: büyük/küçük harf dahil, kırpma yapılmaz. Alfanümerik bir başlık (örneğin NETGSM) ya da hesabın abone numarası olabilir; abone numarası başında 0 ya da 90 olmadan yazılır (5061234567). Kullanabileceğiniz başlıkları ve her birinin kullanılabilir olup olmadığını GET /senders ile görebilirsiniz. Eşleşmezse istek 422 REJECTED_HEADER ile reddedilir; boş ya da yalnızca boşluktan oluşan bir değer ise 400 ile reddedilir.

    Possible values: non-empty and <= 35 characters

    Example: NETGSM
    templates object[]required

    Gönderilecek kayıtlar; her alıcı için bir template. En az 1, en fazla 20 kayıt. Kayıtlardan biri hatalıysa (eksik alan, kullanılamayan template, uymayan parametre) istek 400 ile reddedilir.

    Possible values: >= 1, <= 20

  • Array [
    • templateIdint64required

    Template'in kimliği. Hesabın kendi template'i ya da herkese açık bir template olmalıdır.

    Possible values: >= 1

    Example: 3
    recipientstringrequired

    Alıcı numarası, /send'deki recipient ile aynı biçimde: Türkiye için 90 ve ardından 10 rakam, yurt dışı için - ve ardından 9–17 rakam. Boş ya da 17 karakterden uzunsa istek 400 ile reddedilir; biçime uymayan kayıt template doldurulduktan sonra INVALID_RECIPIENT ile reddedilir.

    Possible values: <= 17 characters, Value must match regular expression ^(90\d{10}|-\d{9,17})$

    Example: 905061234567
    params object

    Template'teki yer tutucuların değerleri: yer tutucu adı → değer. Template'in tanımladığı parametrelerin hepsini boş olmayan değerlerle vermeli, template'te olmayan bir ad vermemelisiniz. Yer tutucusu olmayan bir template'te alan verilmez. Değerler her zaman string olarak yazılır ve parametrenin tanımlı türüne uymalıdır:

    TürKabul edilen
    BIGINTTam sayı, örn. "123456"
    FLOATEn fazla 4 ondalık basamaklı sayı, örn. "12.50"
    TEXTTemplate'te tanımlı uzunluğu aşmayan metin
    DATEdd.MM.yyyy ya da dd/MM/yyyy
    DATETIMEdd.MM.yyyy HH:mm[:ss] ya da dd/MM/yyyy HH:mm[:ss]
    property name*string
  • ]
    • encodingstring

    Metnin karakter kodlaması. Tüm kayıtlara uygulanır. Büyük/küçük harfe duyarlıdır; listede olmayan bir değer (turkish, GSM dahil) istek 400 1 field(s) rejected ile reddedilir; violations alanı (encoding) ve geçerli değerleri belirtir.

    DeğerNe zamanEn fazla uzunluk
    DEFAULTStandart GSM alfabesi. Türkçe karakterler Latin karşılıklarına çevrilir (ç→c, ş→s gibi).917
    TURKISHTürkçe karakterlerin (çğıöşüÇĞİÖŞÜ) korunması gerektiğinde. çğışĞİŞ iki karakter sayılır.888
    UNICODEEmoji ya da Arapça, Kiril gibi GSM alfabesinde olmayan karakterler için.396

    Alfanümerik bir gönderici başlığında her sınır 5 karakter azdır. Sınırı aşan kayıt MESSAGE_TOO_LONG ile reddedilir. Bir metnin kaç SMS'e bölüneceğini POST /length ile hesaplayabilirsiniz.

    Possible values: [DEFAULT, TURKISH, UNICODE]

    Default value: DEFAULT
    iysFilterstring

    İYS (İleti Yönetim Sistemi) izin filtresi; ticari iletilerde alıcının izni olmayanlar gönderimden çıkarılır. Büyük/küçük harf fark etmez:

    DeğerAnlamı
    NONEFiltre yok. Yalnızca bilgilendirme (ticari olmayan) iletiler için.
    BRANDMarka adına alınmış izinlere göre filtrelenir.
    RETAILERBayi adına alınmış izinlere göre filtrelenir.
    BRAND_AND_RETAILERHer ikisine göre filtrelenir.

    Bunların dışındaki her değer NONE sayılır. Hesap ticari gönderim (marka ya da bayi) tipinde tanımlıysa istekteki değer yok sayılır ve hesabın tipi uygulanır.

    BRAND ya da RETAILER uygulanacaksa göndericinin İYS marka kodu olmalıdır; hesap İYS modunda değilse bu iki değer istek 422 REJECTED_IYS ile reddedilir. BRAND_AND_RETAILER için bu iki kontrol yapılmaz.

    Possible values: [NONE, BRAND, RETAILER, BRAND_AND_RETAILER]

    Default value: NONE
    startAtdate-time

    En erken gönderim zamanı, saat dilimi farkıyla (2026-09-10T09:00:00+03:00). Verilmezse ya da geçmişteyse gönderim hemen başlar. 18 aydan daha ilerisi 400 INVALID_SEND_WINDOW ile reddedilir. Bir dakikadan daha ileri bir başlangıç görevi SCHEDULED yapar. Saat dilimi farkı olmayan ya da okunamayan bir tarih istek 400 ile reddedilir.

    stopAtdate-time

    En geç gönderim zamanı, saat dilimi farkıyla. Verilmezse ya da geçmişteyse startAt + 21 saat kabul edilir. Aralık, 1000 ve üzeri mesajda 10 dakikadan, daha azında 5 dakikadan kısaysa bu süreye uzatılır; 21 saatten uzunsa 21 saate kısaltılır. Bu düzeltmeler hata döndürmez ve belirlenen aralık yanıtta yer almaz.

    partnerCodestring

    İş ortağı (bayi) kodu. Yalnızca kayıt amaçlıdır; gönderimi etkilemez.

    Possible values: <= 32 characters

    referenceIdstring

    Yanıtta aynen geri döndürülür.

    Possible values: <= 50 characters

    appNamestring

    Gönderimi yapan uygulamanın adı. Yalnızca kayıt amaçlıdır; gönderimi etkilemez.

    Possible values: <= 50 characters

Responses​

Görev oluşturuldu. İletim sonradan yapılır.

Schema
    jobIdstringrequired

    Oluşturulan görevin numarası. Rapor, istatistik ve iptal için kullanılır; destek taleplerinde belirtmelisiniz.

    statusstringrequired
    DeğerAnlamı
    QUEUEDGönderim hemen başladı; görev iptal edilemez.
    SCHEDULEDGörev startAt zamanına kadar bekletiliyor (dakikaya göre bir dakikadan daha ileri bir başlangıç); o zamana kadar POST /cancel ile iptal edebilirsiniz.

    Possible values: [QUEUED, SCHEDULED]

    acceptedintegerrequired

    Gönderime alınan kayıt sayısı. accepted + rejected, istekteki kayıt sayısına eşittir.

    rejectedintegerrequired

    Reddedilen kayıt sayısı. rejectedItems kısaltılsa da bu sayı tamdır.

    rejectedItems object[]required

    Reddedilen kayıtlar, index sırasıyla ilk 100 tanesi. Hiçbiri reddedilmediyse boş dizi.

    Possible values: <= 100

  • Array [
    • indexintegerrequired

    Kaydın istekteki messages dizisindeki sırası, sıfırdan başlar.

    recipientstringnullablerequired

    Kayıttaki alıcı. Kayıt null ise ya da alıcısı yoksa null.

    reasonstringrequired
    DeğerNe zaman
    INVALID_RECIPIENTNumara eksik ya da biçimi yanlış; bkz. recipient.
    INVALID_MESSAGEMetin eksik ya da boş.
    MESSAGE_TOO_LONGMetin, encoding ve gönderici türüne göre sınırı aşıyor; bkz. encoding.
    MALFORMED_ENTRYKayıt null.
    DUPLICATE_RECIPIENTAynı alıcı istekte daha sonra yeniden geçiyor. Yalnızca son geçen kayıt gönderilir, öncekiler bu nedenle reddedilir; son kayıt başka bir nedenle reddedilse bile. Numaralar yazıldığı gibi karşılaştırılır. Mükerrer gönderime izin verilen hesaplarda uygulanmaz.
    NO_INTERNATIONAL_PERMISSIONNumara yurt dışı (- ile başlıyor) ve hesabın yurt dışı gönderim izni yok. İzin için destek ekibiyle iletişime geçmelisiniz. Yalnızca başka bir hatası olmayan kayıtlarda bildirilir.

    Bir kayıt birden fazla nedenle hatalıysa tek neden bildirilir; öncelik: DUPLICATE_RECIPIENT, MALFORMED_ENTRY, MESSAGE_TOO_LONG, INVALID_RECIPIENT, INVALID_MESSAGE, NO_INTERNATIONAL_PERMISSION.

    Possible values: [INVALID_RECIPIENT, INVALID_MESSAGE, MESSAGE_TOO_LONG, MALFORMED_ENTRY, DUPLICATE_RECIPIENT, NO_INTERNATIONAL_PERMISSION]

  • ]
    • rejectedItemsTruncatedbooleanrequired

    100'den fazla kayıt reddedildiği için rejectedItems kısaltıldıysa true. accepted ve rejected yine tamdır.

    referenceIdstringnullablerequired

    İstekte verilen referenceId; verilmediyse null.

Örnek istek​

curl -X POST 'https://ext-api.netgsm.com.tr/sms/v3/send/template' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "sender": "NETGSM",
  "templates": [
    {
      "templateId": 3,
      "recipient": "905061234567",
      "params": {
        "otpCode": "123456"
      }
    },
    {
      "templateId": 4,
      "recipient": "905061234568"
    }
  ],
  "encoding": "TURKISH",
  "referenceId": "order-4711"
}'