PleaseSMS API · v1

Tek kullanımlık SMS API’si

Müşteri panelinden anahtar oluştur. Anahtarı yalnız sunucunda kullan. Tutarlar USD senti cinsindendir.

Base URLhttps://pleasesms.com/api/v1
cURL · istek
curl -X GET "https://pleasesms.com/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK · yanıt
{
  "amount_minor": 5000,
  "currency": "USD"
}
  • REST · JSONHTTPS üzerinden JSON istek ve yanıtları
  • BearerHer istekte Authorization başlığı
  • USD sentTüm tutarlar amount_minor alanında
  • 60 istek / dkHesap başına istek limiti
01

Hızlı başlangıç

Anahtarı müşteri panelinden oluştur. Her istekte Authorization: Bearer başlığını kullan.

  1. 1Anahtarını oluşturMüşteri panelindeki API ve geliştirici bölümünden tek tıkla anahtar oluştur.
  2. 2Teklif alKatalogdan servis ve ülkeyi seç, hesabına özel güncel teklifi al.
  3. 3Satın al, kodu alTeklifle sipariş ver; sms_code dolana kadar siparişi sorgula.
  1. Bakiye
  2. Servis ve ülke kataloğu
  3. Güncel teklifler
  4. Satın alma
  5. Sipariş ve SMS kodu
02

Kiralık numara ve eSIM

İki izin varsayılan olarak kapalıdır. Müşteri panelinden ayrı ayrı açılır ve aynı anahtar kullanılır. Tutarlar USD sentidir.

Kiralık numara

  • GET/api/v1/products
  • GET/api/v1/rental/catalog
  • GET/api/v1/rental/options?country=TR
  • POST/api/v1/rental/quotes
  • {"country":"TR","term":"30d"}

eSIM

  • GET/api/v1/esim/catalog
  • GET/api/v1/esim/options?location=TR
  • POST/api/v1/esim/quotes
  • {"packageCode":"PACKAGE_CODE","quantity":1}

Kiralık numarada ülke ve süreyi seçeneklerden al. Servise özel kiralama için service ekle. Günlük eSIM paketlerinde days gönder. Her iki üründe de teklifi aşağıdaki satın alma isteğine geçir.

Sipariş ve takip

  • POST/api/v1/{rental|esim}/orders
  • Idempotency-Key: order-0002
  • {"quote_id":"QUOTE_UUID","max_price_minor":550}
  • GET/api/v1/{rental|esim}/orders
  • GET/api/v1/{rental|esim}/orders/{id}
  • POST/api/v1/{rental|esim}/orders/{id}/refresh
  • POST/api/v1/rental/orders/{id}/cancel

Sipariş ayrıntıları kiralık numaranın SMS kutusunu veya eSIM kurulum profilini içerir. Kiralık iptalinde can_cancel alanını kontrol et.

Bakiye

GET/api/v1/balance

Kullanılabilir bakiye. 5000 sent = 50,00 USD. Bakiye aşağı, teklif fiyatı yukarı yuvarlanır.

İstek ve yanıt örnekleri
cURL
curl -X GET "https://pleasesms.com/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "amount_minor": 5000,
  "currency": "USD"
}

Servis ve ülke kataloğu

GET/api/v1/catalog?service=wa

service isteğe bağlıdır. Servis ve ülke için dönen id alanlarını kullan. Stok bilgilendirme amaçlıdır.

İstek ve yanıt örnekleri
cURL
curl -X GET "https://pleasesms.com/api/v1/catalog?service=wa" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "services": [
    {
      "id": "wa",
      "name": "WhatsApp"
    }
  ],
  "countries": [
    {
      "id": "tr",
      "name": "Türkiye",
      "stock": 42
    }
  ]
}

Güncel teklifler

GET/api/v1/offers?service=wa&country=tr

service ve country zorunludur. Stok, satış fiyatı ve teklif bitişi döner. Satın almada bu hesaba ait, süresi geçmemiş teklifi kullan.

İstek ve yanıt örnekleri
cURL
curl -X GET "https://pleasesms.com/api/v1/offers?service=wa&country=tr" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
[
  {
    "id": "00000000-0000-4000-8000-000000000001",
    "service": "wa",
    "country": "tr",
    "price": {
      "amount_minor": 550,
      "currency": "USD"
    },
    "stock": 42,
    "expires_at": "2026-11-14T10:00:30.000Z"
  }
]

Satın alma

POST/api/v1/orders

quote_id ve max_price_minor zorunludur. Idempotency-Key başlığında siparişe özel 8–100 karakter gönder. Ağ hatasında aynı anahtar ve aynı gövde ile tekrar dene.

İstek ve yanıt örnekleri
cURL
curl -X POST "https://pleasesms.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"00000000-0000-4000-8000-000000000001","max_price_minor":550}'
JSON · 201 Created
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "waiting",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}

Sipariş geçmişi

GET/api/v1/orders?offset=0

offset sıfır veya pozitif tam sayıdır. Yanıtta en fazla 50 sipariş döner.

İstek ve yanıt örnekleri
cURL
curl -X GET "https://pleasesms.com/api/v1/orders?offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "service": "wa",
      "country": "tr",
      "price": {
        "amount_minor": 550,
        "currency": "USD"
      },
      "status": "waiting",
      "phone": "+00000000000",
      "sms_code": null,
      "created_at": "2026-11-14T10:00:01.000Z",
      "expires_at": "2026-11-14T10:20:01.000Z",
      "cancel_available_at": "2026-11-14T10:03:01.000Z"
    }
  ]
}

Sipariş ve SMS kodu

GET/api/v1/orders/{id}

Kendi siparişini kimliğiyle sorgula. sms_code boşsa kod henüz teslim edilmemiştir. API siparişlerinde teklifin USD fiyatı korunur. USD kaydı olmayan siparişlerde price null döner. Zaman damgaları UTC ISO 8601 biçimindedir.

İstek ve yanıt örnekleri
cURL
curl -X GET "https://pleasesms.com/api/v1/orders/00000000-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "waiting",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}

Manuel iptal

POST/api/v1/orders/{id}/cancel

cancel_available_at zamanını bekle. SMS geldiyse iptal ve iade yapılamaz. İadeyi refunded durumuyla doğrula.

İstek ve yanıt örnekleri
cURL
curl -X POST "https://pleasesms.com/api/v1/orders/00000000-0000-4000-8000-000000000002/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "refunded",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}
03

Sipariş durumları

  • purchasing / waitingİşleniyor veya SMS bekleniyor.
  • received / completedKod geldi veya işlem tamamlandı.
  • reviewSonuç kontrol ediliyor. Yeni sipariş oluşturmadan mevcut siparişi sorgula.
  • refundedÜcret iade edildi.

Her sipariş için yeni bir Idempotency-Key gönder. Aynı isteği tekrar denerken aynı anahtarı kullan. Kod gelmediyse iptal en erken 180 saniye sonra açılır. Sağlayıcı daha geç bir süre bildirebilir. Webhook henüz yok.

04

Hatalar ve limitler

Limit hesap başına dakikada 60 istektir. Satın alma 201 ile yeni sipariş, 200 ile mevcut/sonuçlanmış sipariş veya 202 ile kontrol edilen sipariş döndürebilir.

400
INVALID_SELECTION / INVALID_PURCHASE / INVALID_OFFSET / INVALID_BODY

Parametreleri, JSON gövdesini ve istek başlıklarını kontrol et.

401
INVALID_API_KEY

Anahtarı ve Bearer başlığını kontrol et.

403
PRODUCT_SCOPE_REQUIRED

Müşteri panelinde ilgili ürün iznini aç.

404
ORDER_NOT_FOUND / NOT_FOUND

Sipariş kimliğini veya adresi kontrol et.

409
QUOTE_EXPIRED / PRICE_LIMIT_EXCEEDED / NO_NUMBERS

Güncel teklif al ve fiyat sınırını kontrol et.

409
INSUFFICIENT_BALANCE

Kullanılabilir bakiyeyi kontrol et.

409
IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESS

Aynı işlemi aynı gövdeyle tekrar sorgula.

409
EARLY_CANCEL_DENIED / CODE_RECEIVED_NO_REFUND / REFUND_NOT_CONFIRMED

Sipariş durumunu ve iptal zamanını sorgula.

429
RATE_LIMITED

Retry-After süresini bekle.

503
SERVICE_UNAVAILABLE / STOCK_CHECK_UNAVAILABLE / EXCHANGE_RATE_UNAVAILABLE

Kısa süre sonra tekrar dene. Satın almada aynı işlem anahtarını kullan.

Hata yanıtı
{
  "error": "QUOTE_EXPIRED"
}