API

Dokumen API

API TODAY SMS ialah API JSON melalui HTTPS. Hantar kunci API anda dalam pengepala Authorization bersama setiap permintaan. Harga, bayaran balik dan masa menunggu 20 minit sama seperti di laman web. Pilih kaedah daripada senarai untuk melihat contoh permintaan dan respons.

Buat kunci API anda di halaman kunci API sebaik sahaja tambah nilai pertama anda dikreditkan. Gantikan YOUR_API_KEY dalam contoh di bawah dengan kunci anda sendiri.

Log masuk Daftar

GET

/balance

Dapatkan baki

Memulangkan baki semasa akaun anda dalam dolar AS. Penerimaan kod dan penghantaran SMS menggunakan baki yang sama.

Parameter

Tiada parameter.

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "balance": "42.5000",
  "currency": "USD"
}

Ralat yang mungkin

unauthorized	Kunci API tiada atau salah
not_allowed	API dibuka selepas tambah nilai pertama anda dikreditkan
rate_limited	Terlalu banyak permintaan dalam 1 minit

GET

/apps

Senarai aplikasi

Menyenaraikan aplikasi yang mempunyai nombor sekarang. Memulangkan kod aplikasi, nama, harga terendah dan bilangan negara yang mempunyai nombor.

Parameter

Tiada parameter.

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/apps \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

[
  { "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]

Ralat yang mungkin

unauthorized	Kunci API tiada atau salah
not_allowed	API dibuka selepas tambah nilai pertama anda dikreditkan

GET

/prices?app=telegram

Negara dan harga bagi sesuatu aplikasi

Memulangkan negara bagi satu aplikasi, yang paling murah dahulu. Termasuk kod negara, kod ISO, harga dan bilangan nombor yang tersedia sekarang.

Parameter

Nama	Jenis	Wajib	Penerangan
app	string	Wajib	Kod aplikasi (nilai app daripada GET /apps)

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/prices?app=telegram \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

[
  { "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]

Ralat yang mungkin

bad_request	Nilai yang diperlukan tiada atau dalam format yang salah
unauthorized	Kunci API tiada atau salah

POST

/numbers

Beli nombor

Membeli nombor untuk aplikasi dan negara yang anda pilih. Harga ditolak daripada baki anda dan nombor menunggu SMS untuk tempoh yang ditetapkan. Jika pengesahan nombor mengambil masa lebih lama, ia memulangkan 202 dengan status sedang menyemak.

Parameter

Nama	Jenis	Wajib	Penerangan
app	string	Wajib	Kod aplikasi
country	string	Wajib	Kod negara (nilai country daripada GET /prices)

Contoh permintaan

request

$ curl -X POST https://today-sms.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app":"telegram","country":"indonesia"}'

Contoh respons

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "app": "telegram",
  "country": "indonesia",
  "phone": "+6281234567890",
  "price": "0.4515",
  "refunded": "0.0000",
  "status": "waiting",
  "expires_at": "2026-10-18T09:20:00.000Z",
  "sms": []
}

Ralat yang mungkin

bad_request	Nilai yang diperlukan tiada atau dalam format yang salah
not_enough_balance	Baki tidak mencukupi, sila tambah nilai dahulu
too_many_open	Terlalu banyak nombor dibuka, sila selesaikan atau batalkan sebahagian
no_numbers	Tiada nombor untuk aplikasi dan negara ini buat masa ini

GET

/numbers/{id}

Status nombor dan SMS

Memulangkan status nombor dan setiap SMS yang diterima setakat ini. Kod pengesahan juga diberikan secara berasingan dalam code.

Parameter

Nama	Jenis	Wajib	Penerangan
id	string	Wajib	id yang anda terima semasa membeli nombor (bermula dengan N-)

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "received",
  "sms": [
    { "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
  ]
}

Ralat yang mungkin

not_found

Tiada nombor atau mesej sedemikian dalam akaun anda

POST

/numbers/{id}/cancel

Batalkan nombor

Membatalkan nombor yang tidak menerima SMS, mulai 120 saat selepas pembelian. Jumlah penuh dikembalikan ke baki anda.

Parameter

Nama	Jenis	Wajib	Penerangan
id	string	Wajib	id nombor (bermula dengan N-)

Contoh permintaan

request

$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "canceled",
  "refunded": "0.4515"
}

Ralat yang mungkin

too_early	Anda boleh membatalkan mulai 120 saat selepas pembelian
has_sms	Nombor yang telah menerima SMS tidak boleh dibatalkan
try_again	Pembatalan belum disahkan, sila cuba lagi dalam 1 minit
not_found	Tiada nombor atau mesej sedemikian dalam akaun anda

POST

/numbers/{id}/finish

Selesaikan nombor

Menutup nombor selepas anda menerima kod. Nombor yang ditutup tidak lagi menerima SMS.

Parameter

Nama	Jenis	Wajib	Penerangan
id	string	Wajib	id nombor (bermula dengan N-)

Contoh permintaan

request

$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "finished"
}

Ralat yang mungkin

not_found

Tiada nombor atau mesej sedemikian dalam akaun anda

GET

/messages/prices

Harga SMS mengikut negara

Memulangkan harga setiap SMS bagi setiap negara untuk penghantaran SMS. Termasuk kod ISO, kod negara dan harga setiap SMS (USD).

Parameter

Tiada parameter.

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/messages/prices \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

[
  { "iso": "us", "dial": "1", "price": "0.0042" },
  { "iso": "gb", "dial": "44", "price": "0.0066" }
]

Ralat yang mungkin

unauthorized	Kunci API tiada atau salah
not_allowed	API dibuka selepas tambah nilai pertama anda dikreditkan

POST

/messages

Hantar SMS

Menghantar SMS kepada senarai penerima dengan mesej anda. Sehingga 1,000 penerima setiap permintaan, dan nombor pendua hanya menerima satu mesej. Tambah at untuk menjadualkan penghantaran pada masa itu (UTC). Jumlah kos ditahan daripada baki anda semasa menghantar, dan bahagian yang gagal dibayar balik ke baki anda.

Parameter

Nama	Jenis	Wajib	Penerangan
to	string[]	Wajib	Senarai nombor dalam format antarabangsa (dengan + dan kod negara), sehingga 1,000
text	string	Wajib	Teks mesej. 160 aksara GSM-7 atau 70 aksara Unicode ialah satu SMS
at	string	Pilihan	Masa berjadual, ISO 8601 UTC (cth. 2026-10-18T10:00:00Z)
ref	string	Pilihan	Rujukan anda sendiri, seperti nombor pesanan, sehingga 64 aksara

Contoh permintaan

request

$ curl -X POST https://today-sms.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["+14155550100","+447700900123"],"text":"Your code is 482913"}'

Contoh respons

response

{
  "id": "m_7Q2K9X",
  "status": "queued",
  "recipients": 2,
  "parts": 1,
  "encoding": "GSM-7",
  "cost": "0.0136"
}

Ralat yang mungkin

bad_request	Nilai yang diperlukan tiada atau dalam format yang salah
too_many_recipients	Sehingga 1,000 penerima setiap permintaan
not_enough_balance	Baki tidak mencukupi, sila tambah nilai dahulu
not_available	Produk ini akan dibuka tidak lama lagi. Permintaan ini tidak diterima dan baki anda tidak berubah

GET

/messages/{id}

Status penghantaran dan laporan penghantaran

Memulangkan status keseluruhan mesej yang dihantar dan laporan penghantaran bagi setiap penerima. Jumlah untuk bahagian yang gagal ditambah ke refunded.

Parameter

Nama	Jenis	Wajib	Penerangan
id	string	Wajib	id yang anda terima semasa menghantar

Contoh permintaan

request

$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "id": "m_7Q2K9X",
  "status": "done",
  "cost": "0.0136",
  "refunded": "0.0083",
  "reports": [
    { "to": "+14155550100", "status": "delivered", "at": "2026-10-18T10:00:04Z" },
    { "to": "+447700900123", "status": "failed", "at": "2026-10-18T10:00:09Z" }
  ]
}

Ralat yang mungkin

not_found

Tiada nombor atau mesej sedemikian dalam akaun anda

POST

/messages/{id}/cancel

Batalkan penghantaran berjadual

Membatalkan penghantaran berjadual yang belum dihantar. Jumlah penuh yang ditahan dikembalikan ke baki anda.

Parameter

Nama	Jenis	Wajib	Penerangan
id	string	Wajib	id mesej

Contoh permintaan

request

$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

response

{
  "id": "m_7Q2K9X",
  "status": "canceled",
  "refunded": "0.0136"
}

Ralat yang mungkin

too_late	Mesej yang telah mula dihantar tidak boleh dibatalkan
not_found	Tiada nombor atau mesej sedemikian dalam akaun anda

URL asas

base

https://today-sms.com/api/v1

Pengesahan identiti

Pengepala Authorization: Bearer YOUR_API_KEY. Buat kunci di halaman kunci API sebaik sahaja tambah nilai pertama anda dikreditkan. Anda boleh membuat sehingga 300 permintaan seminit.

auth

$ curl https://today-sms.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Format

Badan permintaan dan respons dalam JSON (UTF-8). Jumlah ialah rentetan dolar AS dengan sehingga 4 tempat perpuluhan, dan masa dalam ISO 8601 UTC.

Status nombor

waiting	Nombor sedia, belum ada SMS
received	Satu atau lebih SMS telah tiba
finished	Ditutup selepas kod diterima
canceled	Dibatalkan, bayaran balik penuh
expired	Tiada SMS dalam tempoh, bayaran balik penuh
checking	Sedang menyemak nombor, dibayar balik jika tiada nombor sehingga tamat masa

Status penghantaran SMS

queued	Menunggu untuk dihantar
scheduled	Berjadual, dihantar pada masa yang ditetapkan
sending	Sedang dihantar
done	Keputusan telah diterima untuk semua penerima
canceled	Jadual dibatalkan, bayaran balik penuh

Status penghantaran bagi setiap penerima

pending	Belum diserahkan kepada syarikat telekomunikasi
sent	Diserahkan kepada syarikat telekomunikasi
delivered	Diterima di telefon penerima
failed	Gagal, jumlah bagi bahagian itu dibayar balik ke baki

Ralat

Ralat memulangkan kod status bukan 2xx dan JSON dengan nilai error.

error

{
  "error": "not_enough_balance"
}

unauthorized	Kunci API tiada atau salah
not_allowed	API dibuka selepas tambah nilai pertama anda dikreditkan
bad_request	Nilai yang diperlukan tiada atau dalam format yang salah
no_numbers	Tiada nombor untuk aplikasi dan negara ini buat masa ini
not_enough_balance	Baki tidak mencukupi, sila tambah nilai dahulu
too_many_open	Terlalu banyak nombor dibuka, sila selesaikan atau batalkan sebahagian
too_early	Anda boleh membatalkan mulai 120 saat selepas pembelian
has_sms	Nombor yang telah menerima SMS tidak boleh dibatalkan
not_found	Tiada nombor atau mesej sedemikian dalam akaun anda
try_again	Pembatalan belum disahkan, sila cuba lagi dalam 1 minit
rate_limited	Terlalu banyak permintaan dalam 1 minit
too_many_recipients	Sehingga 1,000 penerima setiap permintaan
too_late	Mesej yang telah mula dihantar tidak boleh dibatalkan
not_available	Produk ini akan dibuka tidak lama lagi. Permintaan ini tidak diterima dan baki anda tidak berubah