API Belgeleri

v1.0.0

Sanal numaralara, siparişlere ve hesap bakiyesine programatik erişim.

⟩ Kimlik Doğrulama

Tüm API istekleri bir Bearer token gerektirir. Paneldeki Hesap Ayarları'ndan bir tane oluşturun ve her istekte ekleyin:

Authorization: Bearer YOUR_API_TOKEN

Geçerli bir token içermeyen istekler 401 UNAUTHORIZED yanıtı alır.

⟩ Temel URL

Aşağıdaki tüm endpoint yolları şuna görelidir:

https://api.smscode.gg/v1

⟩ Yanıt Formatı

Her yanıt tutarlı bir zarfla JSON döndürür. Tüm yanıtlar hata ayıklama için bir x-request-id başlığı içerir.

  Başarılı 
 {
  "success": true,
  "data": { ... }
} 

  Hata 
 {
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
} 

GET /catalog/countries

Tüm mevcut ülkelerin listesini döndürür.

Parametreler

Yok

Örnek İstek

curl -s https://api.smscode.gg/v1/catalog/countries \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/countries", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/countries",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": [
    {
      "id": 6,
      "code": "ID",
      "name": "Indonesia",
      "dial_code": "+62",
      "emoji": "🇮🇩",
      "active": true
    }
  ]
}

GET /catalog/services

Mevcut hizmetlerin (platformların) listesini döndürür. İsteğe bağlı olarak ülkeye göre filtreleyin.

Sorgu Parametreleri

Ad	Tür	Zorunlu	Açıklama
`country_id`	integer	Hayır	Bu ülke için mevcut hizmetleri filtrele

Örnek İstek

curl -s "https://api.smscode.gg/v1/catalog/services?country_id=6" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/services?country_id=6", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/services",
    params={"country_id": 6},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": [
    {
      "id": 3,
      "code": "wa",
      "name": "WhatsApp",
      "active": true
    }
  ]
}

GET /catalog/products

Mevcut ürünlerin sayfalanmış listesini döndürür. Ülke ve/veya platforma göre filtreleyin.

Sorgu Parametreleri

Ad	Tür	Zorunlu	Açıklama
`country_id`	integer	Hayır	Ülke kimliğine göre filtrele
`platform_id`	integer	Hayır	Platform/hizmet kimliğine göre filtrele
`sort`	string	Hayır	Sıralama: price_asc (varsayılan), price_desc, available_asc, available_desc, name_asc, name_desc
`limit`	integer	Hayır	Sayfa başına sonuç (1-10.000, varsayılan 1.000)
`page`	integer	Hayır	Sayfa numarası (min 1, varsayılan 1)

Örnek İstek

curl -s "https://api.smscode.gg/v1/catalog/products?country_id=6&platform_id=3&limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  country_id: "6", platform_id: "3", limit: "10", page: "1",
});
const res = await fetch(`https://api.smscode.gg/v1/catalog/products?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/products",
    params={"country_id": 6, "platform_id": 3, "limit": 10, "page": 1},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": [
    {
      "id": 142,
      "name": "WhatsApp Indonesia",
      "country_id": 6,
      "platform_id": 3,
      "available": 42,
      "price": 15000,
      "active": true
    }
  ],
  "meta": { "page": 1, "limit": 10, "count": 1 }
}

GET /catalog/exchange-rate

Bir döviz çifti için güncel döviz kurunu döndürür. Fiyat dönüştürme için kullanışlıdır.

Sorgu Parametreleri

Ad	Tür	Zorunlu	Açıklama
`pair`	string	Hayır	Döviz çifti (varsayılan: USD/IDR)

Örnek İstek

curl -s "https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/catalog/exchange-rate",
    params={"pair": "USD/IDR"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "pair": "USD/IDR",
    "base_currency": "USD",
    "quote_currency": "IDR",
    "rate": 16250
  }
}

GET /balance

Kimliği doğrulanmış kullanıcının hesap bakiyesini IDR cinsinden döndürür.

Parametreler

Yok

Örnek İstek

curl -s https://api.smscode.gg/v1/balance \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/balance", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/balance",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "currency": "IDR",
    "balance": 500000
  }
}

GET /orders

Kimliği doğrulanmış kullanıcının siparişlerini en yeniden eskiye sıralı olarak döndürür. Duruma göre filtreleme ve offset ile sayfalamayı destekler.

Sorgu Parametreleri

Ad	Tür	Zorunlu	Açıklama
`limit`	integer	Hayır	Maksimum sonuç (1-100, varsayılan 20)
`offset`	integer	Hayır	Atlanacak sonuç sayısı (varsayılan 0)
`status`	string	Hayır	Duruma göre filtrele: ACTIVE, OTP_RECEIVED, COMPLETED, CANCELED, EXPIRED (büyük/küçük harf duyarsız)

Örnek İstek

curl -s "https://api.smscode.gg/v1/orders?limit=5&status=ACTIVE" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const params = new URLSearchParams({
  limit: "5", status: "ACTIVE", offset: "0",
});
const res = await fetch(`https://api.smscode.gg/v1/orders?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders",
    params={"limit": 5, "status": "ACTIVE", "offset": 0},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "ACTIVE",
      "created_at": "2026-02-25T10:00:00Z",
      "product_id": 142,
      "phone_number": "+6281234567890",
      "amount": 15000,
      "otp_code": null,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:20:00Z",
      "canceled_at": null,
      "failed_reason": null
    }
  ]
}

GET /orders/{id}

Kimliğe göre tek bir siparişi döndürür. Yalnızca kimliği doğrulanmış kullanıcıya ait siparişleri döndürür.

Yol Parametreleri

Ad	Tür	Zorunlu	Açıklama
`id`	integer	Evet	Sipariş kimliği (yol parametresi)

Örnek İstek

curl -s https://api.smscode.gg/v1/orders/1001 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/orders/1001", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders/1001",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "id": 1001,
    "status": "OTP_RECEIVED",
    "created_at": "2026-02-25T10:00:00Z",
    "product_id": 142,
    "phone_number": "+6281234567890",
    "amount": 15000,
    "otp_code": "123456",
    "otp_received_at": "2026-02-25T10:05:00Z",
    "expires_at": "2026-02-25T10:20:00Z",
    "canceled_at": null,
    "failed_reason": null
  }
}

GET /orders/active

Tüm aktif siparişleri (ACTIVE + OTP_RECEIVED) listeler. OTP durumu güncellemelerini sorgulamak için kullanın.

Parametreler

Yok

Örnek İstek

curl -s https://api.smscode.gg/v1/orders/active \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/orders/active", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/orders/active",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "status": "OTP_RECEIVED",
      "otp_code": "123456",
      "otp_message": "Your verification code is 123456",
      "otp_received_at": "2026-02-25T10:05:00Z",
      "expires_at": "2026-02-25T10:20:00Z",
      "failed_reason": null
    },
    {
      "id": 1002,
      "status": "ACTIVE",
      "otp_code": null,
      "otp_message": null,
      "otp_received_at": null,
      "expires_at": "2026-02-25T10:50:00Z",
      "failed_reason": null
    }
  ]
}

POST /orders/create

Yeni bir sanal numara siparişi oluşturur. Bakiyeyi otomatik olarak düşer. Ağ yeniden denemelerinde yinelenen siparişleri önlemek için isteğe bağlı Idempotency-Key başlığını destekler.

İstek Gövdesi

Ad	Tür	Zorunlu	Açıklama
`product_id`	integer	Evet	Sipariş verilecek ürün kimliği
`quantity`	integer	Hayır	Adet sayısı (1-100, varsayılan 1)

Yinelenen siparişler oluşturmadan güvenle yeniden deneme yapmak için Idempotency-Key başlığı (herhangi bir benzersiz dize) gönderin.

Örnek İstek

curl -s -X POST https://api.smscode.gg/v1/orders/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"product_id":142,"quantity":1}'

const res = await fetch("https://api.smscode.gg/v1/orders/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Idempotency-Key": "unique-request-id-123",
  },
  body: JSON.stringify({ product_id: 142, quantity: 1 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/create",
    json={"product_id": 142, "quantity": 1},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Idempotency-Key": "unique-request-id-123",
    })
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1002,
        "status": "ACTIVE",
        "phone_number": "+6281234567891",
        "otp_code": null,
        "otp_received_at": null,
        "expires_at": "2026-02-25T10:50:00Z",
        "failed_reason": null
      }
    ],
    "failed_count": 0
  }
}

POST /orders/cancel

Aktif bir siparişi iptal eder. Kiralama bedeli hesap bakiyenize iade edilir.

İstek Gövdesi

Ad	Tür	Zorunlu	Açıklama
`id`	integer	Evet	İptal edilecek sipariş kimliği

Örnek İstek

curl -s -X POST https://api.smscode.gg/v1/orders/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/cancel", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/cancel",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "CANCELED",
    "refund_amount": 15000,
    "new_balance": 515000
  }
}

POST /orders/finish

OTP alındıktan sonra siparişi tamamlandı olarak işaretler. Süre dolmasını beklemek yerine numarayı hemen serbest bırakır.

İstek Gövdesi

Ad	Tür	Zorunlu	Açıklama
`id`	integer	Evet	Tamamlanacak sipariş kimliği

Örnek İstek

curl -s -X POST https://api.smscode.gg/v1/orders/finish \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/finish", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/finish",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "COMPLETED"
  }
}

POST /orders/resend

Platformdan kiralanan numaraya SMS'i yeniden göndermesini ister. Tüm platformlar yeniden gönderimi desteklemez — yanıttaki resent alanını kontrol edin.

İstek Gövdesi

Ad	Tür	Zorunlu	Açıklama
`id`	integer	Evet	SMS yeniden gönderilecek sipariş kimliği

Örnek İstek

curl -s -X POST https://api.smscode.gg/v1/orders/resend \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":1001}'

const res = await fetch("https://api.smscode.gg/v1/orders/resend", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/orders/resend",
    json={"id": 1001},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "order_id": 1001,
    "status": "ACTIVE",
    "resent": true
  }
}

GET /webhook

Mevcut webhook bildirim yapılandırmanızı döndürür.

Parametreler

Yok

Örnek İstek

curl -s https://api.smscode.gg/v1/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/webhook", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.get("https://api.smscode.gg/v1/webhook",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

PATCH /webhook

Webhook URL'nizi ve/veya gizli anahtarınızı güncelleyin. İlk kez URL belirlediğinizde gizli anahtar otomatik oluşturulur. Temizlemek için boş dize gönderin. URL HTTPS kullanmalıdır.

İstek Gövdesi

Ad	Tür	Zorunlu	Açıklama
`webhook_url`	string	Hayır	Webhook olaylarını alacak HTTPS URL'si (temizlemek için boş dize)
`webhook_secret`	string	Hayır	HMAC-SHA256 imzası için paylaşılan gizli anahtar (ilk ayarlamada belirtilmezse otomatik oluşturulur)

En az bir alan gereklidir.

Örnek İstek

curl -s -X PATCH https://api.smscode.gg/v1/webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://example.com/webhook"}'

const res = await fetch("https://api.smscode.gg/v1/webhook", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ webhook_url: "https://example.com/webhook" }),
});
const data = await res.json();

import requests

res = requests.patch("https://api.smscode.gg/v1/webhook",
    json={"webhook_url": "https://example.com/webhook"},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "webhook_url": "https://example.com/webhook",
    "webhook_secret": "a1b2c3d4e5f6..."
  }
}

POST /webhook/test

Yapılandırılmış webhook URL'nize bir test olayı gönderir. Sunucunuzdan dönen HTTP durum kodunu döndürür. Canlıya geçmeden önce endpoint'inizin çalıştığını doğrulamak için kullanışlıdır.

Parametreler

Yok

Örnek İstek

curl -s -X POST https://api.smscode.gg/v1/webhook/test \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch("https://api.smscode.gg/v1/webhook/test", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();

import requests

res = requests.post("https://api.smscode.gg/v1/webhook/test",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()

Örnek Yanıt

200 OK

{
  "success": true,
  "data": {
    "status_code": 200
  }
}

⟩ Webhook Bildirimleri

Polling yerine sipariş olayları için gerçek zamanlı push bildirimleri almak üzere bir webhook URL'si yapılandırın. Bu, bot betikleri için önerilen yaklaşımdır.

Olaylar

Olay	Tetikleyici
`order.otp_received`	Kiralanan numaraya OTP kodu teslim edildi
`order.completed`	Sipariş tamamlandı olarak işaretlendi (manuel olarak veya süre dolmasıyla)
`order.expired`	Sipariş OTP alınmadan süresi doldu (bakiye iade edildi)
`order.canceled`	Sipariş kullanıcı tarafından iptal edildi (bakiye iade edildi)

Veri Yükü

  Webhook POST Gövdesi 
 {
  "event": "order.otp_received",
  "timestamp": "2026-02-25T12:00:00Z",
  "data": {
    "order_id": 1001,
    "phone_number": "+628123456789",
    "otp_code": "1234",
    "otp_message": "Your verification code is 1234",
    "product_id": 42,
    "country": "Indonesia",
    "platform": "WhatsApp"
  }
} 

İmza Doğrulama

Her webhook isteği, webhook_secret'ınızı anahtar olarak kullanarak istek gövdesinin HMAC-SHA256 imzasını içeren bir X-Webhook-Signature başlığı içerir:

X-Webhook-Signature: sha256={HMAC-SHA256(body, webhook_secret)}

İsteğin gerçek olduğundan emin olmak için bu imzayı sunucunuzda doğrulayın. Teslim, 3 saniyelik zaman aşımıyla tek seferlik gönderimdir ve yeniden deneme yapılmaz.

⟩ Rate Limit'ler

API isteklerine endpoint grubuna göre rate limit uygulanır. Limiti aşmak, kaç saniye bekleneceğini belirten bir Retry-After başlığıyla birlikte 429 Too Many Requests döndürür.

Endpoint Grubu	Limit	Pencere
Katalog (ülkeler, hizmetler, ürünler, döviz kuru)	1.200 istek	60 saniye
Bakiye	600 istek	60 saniye
Sipariş okumaları (liste, tekil, aktif)	1.200 istek	60 saniye
Sipariş oluşturma	1.200 istek	60 saniye
Sipariş iptali	600 istek	60 saniye
Sipariş işlemleri (tamamla, yeniden gönder)	600 istek	60 saniye
Webhook yapılandırması (al, güncelle, test)	120 istek	60 saniye

⟩ Hata Kodları

error.code içinde aşağıdaki kodlardan biri yer alır:

Kod	HTTP	Açıklama
`UNAUTHORIZED`	401	Eksik veya geçersiz API token
`FORBIDDEN`	403	Erişim reddedildi
`NOT_FOUND`	404	Kaynak bulunamadı (sipariş, döviz kuru vb.)
`CONFLICT`	409	Yinelenen istek veya kaynak çakışması
`INSUFFICIENT_BALANCE`	409	Sipariş oluşturmak için yeterli bakiye yok
`VALIDATION_ERROR`	422	İstek parametreleri doğrulamayı geçemedi
`RATE_LIMIT_EXCEEDED`	429	Çok fazla istek (`Retry-After` başlığını kontrol edin)
`INTERNAL_ERROR`	500	Sunucu iç hatası
`PROVIDER_ERROR`	422	Üst düzey SMS sağlayıcısı isteği reddetti
`CANCEL_TOO_EARLY`	409	Sipariş iptal etmek için çok yeni — 2 dakika bekleyin
`SERVICE_UNAVAILABLE`	503	Hizmet geçici olarak kullanılamıyor (bakım)