---
title: "SMS Gönderme API (send-sms)"
description: "send-sms endpoint'i ile tek seferde tek veya çoklu numaraya SMS gönderirsiniz. Sender ID, İYS bayrağı, mesaj metni ve alıcı listesi ile çalışır."
slug: /docs/api/send-sms
locale: tr
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/send-sms/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [authentication, get-report, get-sender, get-balance, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/send-sms
  en: https://www.iletimerkezi.com/en/docs/api/send-sms
  toplusmsapi: https://toplusmsapi.com/sms/gonder/json
  a2psmsapi: https://a2psmsapi.com/en/sms/gonder/json
---

# SMS Gönderme API (send-sms)

`send-sms` endpoint'i tek bir istekle bir veya birden çok cep telefonuna SMS gönderir. İstek bir **sipariş (order)** olarak kabul edilir; başarılı yanıtta dönen `orderId` ile teslimat raporlarını takip edebilir, ileri tarihli siparişleri iptal edebilirsiniz. İstek başına yalnızca bir sipariş, sipariş başına bir sender (başlık) gönderilir.

## Önemli ön koşul: Panel'de API erişimi

> Bu endpoint'i çağırmadan önce panelinizde **API kullanımına izin ver** seçeneğinin aktif olması gerekir.
>
> Ayar yeri: `panel.iletimerkezi.com` → **Ayarlar → Güvenlik → Erişim İzinleri**
>
> Aktif değilse istek `401 — Üyelik bilgileri hatalı` ile döner. Detay: [authentication.md](./authentication.md)

## Endpoint

| Alan | Değer |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/send-sms/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Şema

```
request
├─ authentication
│  ├─ key (string, zorunlu)
│  └─ hash (string, zorunlu)
└─ order
   ├─ sender (string, zorunlu)         — panelde onaylı sender ID, max 11 karakter
   ├─ iys (string, zorunlu)             — "1" veya "0"
   ├─ iysList (string, koşullu)         — iys=1 ise "BIREYSEL" veya "TACIR"
   ├─ sendDateTime (string[], opsiyonel) — ileri tarih, format "GG/AA/YYYY SS:DD"
   └─ message
      ├─ text (string, zorunlu)         — SMS metni
      └─ receipents
         └─ number (string[], zorunlu)  — 905xxxxxxxxx, +905xxxxxxxxx, 5xxxxxxxxx kabul edilir
```

> `iys` alanı her zaman zorunludur. Ticari (kampanya, reklam, tebrik) mesajlar için `"1"` ve uygun `iysList` değeri (`BIREYSEL` ya da `TACIR`) gönderilmelidir; aksi halde yasal yaptırım uygulanabilir. Bilgilendirme, onay/OTP, abonelik, teslimat gibi mevzuat dışı/transactional mesajlarda `"0"` gönderilir, `iysList` yok sayılır.

> `receipents` (sic.) alanı **`message` altındadır**, `order` altında değil. Eski örneklerde `order.receipents` görülebilir, doğrusu `order.message.receipents`'tir.

### Tam örnek

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "order": {
      "sender": "BASLIGINIZ",
      "iys": "0",
      "message": {
        "text": "Sipariş #1234 hazırlandı, kargoya verildi.",
        "receipents": {
          "number": ["905XXXXXXXXX"]
        }
      }
    }
  }
}
```

Birden fazla alıcı için aynı `number` dizisine ekleyin:

```json
"receipents": {
  "number": ["905XXXXXXXXX", "905YYYYYYYYY", "905ZZZZZZZZZ"]
}
```

## Response

### Başarılı (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "order": {
      "id": "312891245"
    }
  }
}
```

**Alanlar:**

- `response.status.code` (integer): HTTP durum koduna paralel iç durum kodu
- `response.status.message` (string): Türkçe açıklama
- `response.order.id` (string): Siparişe atanan eşsiz numerik ID. Teslimat raporu ([`get-report`](./get-report.md)) ve ileri tarih siparişlerinin iptali için bu ID kullanılır.

### Hata yanıtları

#### 401 — Üyelik bilgileri hatalı

API Anahtar/Hash doğrulanamadı veya panel toggle kapalı. Detay: [authentication.md](./authentication.md).

#### 451 — Tekrar eden sipariş

Aynı sender + alıcı + mesaj metni kombinasyonu kısa süre içinde yeniden gönderildi (idempotency koruması). Mesaj metnini değiştirin veya bir önceki siparişin durumunu [`get-report`](./get-report.md) ile kontrol edin.

#### 452 — Mesaj alıcıları hatalı

`receipents.number` boş, geçersiz formatta veya alanı tamamen eksik. En yaygın sebep: `receipents`'in yanlış yere (`order.receipents` gibi) yerleştirilmiş olması. Doğru konum: `order.message.receipents`.

#### Diğer hata kodları

`400, 402, 450, 453, 454, 457, 468, 469, 470` kodları için tam tablo: [error-codes.md](./error-codes.md).

## Kod örnekleri

### cURL

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/send-sms/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "order": {
        "sender": "BASLIGINIZ",
        "iys": "0",
        "message": {
          "text": "Sipariş hazırlandı, kargoya verildi.",
          "receipents": { "number": ["905XXXXXXXXX"] }
        }
      }
    }
  }'
```


## Common Pitfalls

- **`receipents` yerini şaşırma.** Pattern `order.message.receipents.number[]`'dir, `order.receipents` değil. Eski örneklerde yanlış yer görülür; 452 alıyorsanız ilk kontrol edilecek nokta budur.
- **`iys` zorunlu, default'u yok.** Alanı atlarsanız istek geçmez. Ticari mesajlarda `"1"` + `iysList` zorunlu; aksi halde yasal yaptırım söz konusudur.
- **Sender panelde onaylı olmalı.** `eMarka Test` gibi başlıklar panel onayı gerektirir; onaylı listeyi [`get-sender`](./get-sender.md) endpoint'i ile çekebilirsiniz. Onayı beklerken sender değerini `"APITEST"` yaparak HTTP entegrasyonunu test edebilirsiniz (mesaj metni sabit bir test metniyle değiştirilir, akış tam çalışır). Detay: [test-mode](./test-mode.md).
- **Tekrar eden siparişe dikkat.** Aynı `sender + numara + text` kısa zaman aralığında gönderilirse `451` döner. İdempotent kullanımda mesaj sonuna unique bir referans (sipariş ID, timestamp) ekleyin.
- **Numara formatı esnek ama tutarlı kullanın.** `905XXXXXXXXX`, `+905XXXXXXXXX`, `5XXXXXXXXX` kabul edilir. Tek bir formatta kalmak hata ayıklamayı kolaylaştırır; tercihen `905XXXXXXXXX` (12 hane).
- **Yurt dışı numara için yurt dışı modu gerekir.** Türkiye dışı country code (`+49`, `+44` vb.) ile gönderim yapmak için panelden **Ayarlar → SMS → Yurt Dışı** modunu aktifleştirin. Aktivasyon kontör bakiyesini TL bakiyeye çevirir; sonra bu modda kalırsınız. Detay: [overview](./overview.md).
- **Bakiyeyi öncesi/sonrası karşılaştırın.** Test ortamında [`get-balance`](./get-balance.md) ile her gönderim öncesi ve sonrası bakiyeyi loglayın. Mesaj uzunluğu (eMarka karakter limitleri B186 prefix sebebiyle: İngilizce 155/153, Türkçe 150/148, Unicode 65/63), karakter modu (`sendDateTime` ile ileri tarihli sipariş, çok-parçalı mesaj) gibi etkenler kontör tüketimini etkiler. Detay: [overview](./overview.md).
- **Maksimum 7 parça / ~1071 karakter.** Tek mesaj 7 parçayı geçemez. Daha uzun içerik ya kısaltılmalı ya da iim.to kısa link ile dağıtılmalı.
- **Teslim edilmeyen SMS ücretsizdir.** Kapalı hat, geçersiz numara veya kara liste sebebiyle teslim edilmeyen mesajlar için kontör harcanmaz. [`get-report`](./get-report.md) `delivered` ve `price` alanlarından gerçek tüketim okunur.
- **Sender ID 11 karakter sınırı.** Maksimum 11 karakter; alfanumerik. Boşluk hesaba katılır.
- **Mesaj metni karakter ekonomisi.** Uzun URL'leri ham olarak yapıştırırsanız ilk SMS karakter sınırına (155 / 150 / 65) hızla çarparsınız. iletiMerkezi panelinden `iim.to/...` kısa linki oluşturup mesaja yapıştırın; tıklama raporları ve otomatik çıkış (opt-out) akışı da bu link üzerinden işler. Kısa link şu an panelden yönetilir, ayrı API endpoint'i yoktur.


## Related

- [Kimlik doğrulama (authentication)](./authentication.md)
- [Onaylı sender ID listesi (get-sender)](./get-sender.md)
- [Teslimat raporu (get-report)](./get-report.md)
- [Bakiye sorgulama (get-balance)](./get-balance.md)
- [Hata kodları tablosu](./error-codes.md)