معرفی API
API ارسال پیامک SMSHosting به شما امکان میدهد تا از طریق یک درخواست ساده HTTP GET، پیامکهای OTP، تبلیغاتی و خدماتی را به صورت خودکار از نرمافزار، وبسایت یا اپلیکیشن خود ارسال کنید.
نکته مهم
این API از روش HTTP GET استفاده میکند و پاسخ آن به صورت
JSON برگردانده میشود.
سرعت تحویل
زیر ۳ ثانیه
تعداد درخواست
نامحدود
پشتیبانی از پترن
بله
آدرس Endpoint
برای ارسال پیامک، درخواست خود را به آدرس زیر ارسال کنید:
ساختار کامل درخواست
?tel=<Phone_number>
&template=<template_name>
&key=<merchant_key>
&token=<COTP_CODE>
توجه
تمامی پارامترها باید به صورت URL Encoded ارسال شوند. در صورت استفاده از کاراکترهای خاص در متن، حتماً از انکودینگ مناسب استفاده کنید.
پارامترهای ورودی
| پارامتر | نوع | وضعیت | توضیحات |
|---|---|---|---|
tel |
String | الزامی |
شماره تلفن گیرنده به صورت ۱۱ رقمی (مثال: 09123456789)
|
template |
String | الزامی |
نام الگوی پیامک. برای OTP مقدار otp را قرار دهید.
|
key |
String | الزامی | کلید اختصاصی merchant که در پنل کاربری قابل دریافت است. |
token |
String | الزامی | مقدار متغیر اول الگو. برای OTP همان کد تأیید است. |
token2 |
String | اختیاری | مقدار متغیر دوم الگو (در صورت وجود در الگو). |
token3 |
String | اختیاری | مقدار متغیر سوم الگو (در صورت وجود در الگو). |
درباره template و token
الگوهای پیامکی در پنل کاربری تعریف میشوند. به عنوان مثال، الگوی
otp
ممکن است به این شکل باشد:
کد تأیید شما: {token}
در این حالت، مقدار token
جایگزین {token} میشود.
اگر الگو دارای چند متغیر باشد، از
token2 و
token3
استفاده کنید.
پاسخ سرور
نوع پاسخ
پاسخ این API به صورت متن ساده (Plain Text) برگردانده میشود، نه JSON. مقدار پاسخ یکی از دو حالت زیر خواهد بود:
پاسخ موفق
پاسخ ناموفق
نکته مهم
برای تشخیص موفقیت ارسال، کافی است بررسی کنید که پاسخ دریافتی شامل عبارت
send ok باشد.
در غیر این صورت، ارسال ناموفق بوده است.
نمونه کدها
# ارسال OTP ساده curl -X GET "http://sms.javahosting.ir/sendsms1?tel=09123456789&template=otp&key=YOUR_MERCHANT_KEY&token=12345" # ارسال با چند متغیر (token2, token3) curl -X GET "http://sms.javahosting.ir/sendsms1?tel=09123456789&template=order&key=YOUR_MERCHANT_KEY&token=علی&token2=12345&token3=1403/05/15"
کدهای خطا
| کد | پیام | راهحل |
|---|---|---|
200 |
موفق | پیام با موفقیت ارسال شده است |
400 |
درخواست نامعتبر | پارامترهای ارسالی را بررسی کنید |
401 |
کلید نامعتبر | مقدار key را از پنل کاربری کپی کنید |
403 |
دسترسی مسدود | IP شما در لیست مجاز نیست |
404 |
الگو یافت نشد | نام الگو را در پنل بررسی کنید |
429 |
تعداد درخواست زیاد | محدودیت Rate Limit را رعایت کنید |
500 |
خطای سرور | لطفاً با پشتیبانی تماس بگیرید |
نکات امنیتی
محافظت از Merchant Key
کلید اختصاصی شما مانند رمز عبور است. آن را در کد سمت کلاینت (JavaScript) قرار ندهید و حتماً از سمت سرور اقدام به ارسال کنید.
محدودیت IP
در پنل کاربری خود میتوانید لیست IPهای مجاز را تنظیم کنید تا فقط سرورهای شما امکان ارسال پیامک داشته باشند.
Rate Limiting
برای جلوگیری از سوءاستفاده، محدودیت تعداد درخواست در دقیقه و روز اعمال میشود. در صورت نیاز به محدودیت بالاتر، با پشتیبانی تماس بگیرید.
HTTPS
در محیط عملیاتی حتماً از نسخه https://
استفاده کنید تا اطلاعات شما رمزنگاری شود.
سوالات متداول API
چطور میتوانم Merchant Key خود را دریافت کنم؟
پس از ورود به پنل کاربری، به بخش «تنظیمات API» بروید و کلید اختصاصی خود را کپی کنید.
آیا میتوانم بدون تعریف الگو پیامک ارسال کنم؟
خیر. برای ارسال از طریق این API، ابتدا باید الگوی پیامکی خود را در پنل کاربری تعریف کنید. سپس با استفاده از نام الگو و متغیرها، پیامک ارسال کنید.
حداکثر تعداد متغیر در الگو چقدر است؟
بسته به نوع الگو، میتوانید تا ۳ متغیر (token, token2, token3) ارسال کنید. در صورت نیاز به متغیرهای بیشتر، با پشتیبانی تماس بگیرید.
چرا پیامک من ارسال نمیشود؟
دلایل رایج: ۱) موجودی ناکافی ۲) کلید نامعتبر ۳) IP غیرمجاز ۴) نام الگو اشتباه ۵) شماره گیرنده در لیست سیاه. لطفاً لاگهای پنل را بررسی کنید.
آیا API از ارسال گروهی پشتیبانی میکند؟
بله. برای ارسال گروهی، کافی است درخواست را به تعداد شمارهها تکرار کنید یا از سرویس Bulk SMS استفاده کنید.
نیاز به کمک دارید؟
تیم فنی ما آماده پاسخگویی به سوالات شما درباره API است