پرتال مادر جاواهاست | دسترسی به ۲۲+ سرویس تخصصی از یک جا
javahost.org
📚

مستندات API ارسال پیامک

راهنمای کامل اتصال به API ارسال پیامک SMSHosting
ارسال OTP، تبلیغاتی و خدماتی با یک درخواست ساده HTTP

سرعت بالا امنیت کامل REST API HTTP GET

معرفی API

API ارسال پیامک SMSHosting به شما امکان می‌دهد تا از طریق یک درخواست ساده HTTP GET، پیامک‌های OTP، تبلیغاتی و خدماتی را به صورت خودکار از نرم‌افزار، وب‌سایت یا اپلیکیشن خود ارسال کنید.

نکته مهم

این API از روش HTTP GET استفاده می‌کند و پاسخ آن به صورت JSON برگردانده می‌شود.

سرعت تحویل

زیر ۳ ثانیه

تعداد درخواست

نامحدود

پشتیبانی از پترن

بله

آدرس Endpoint

برای ارسال پیامک، درخواست خود را به آدرس زیر ارسال کنید:

GET http://sms.javahosting.ir/sendsms1

ساختار کامل درخواست

http://sms.javahosting.ir/sendsms1
  ?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. مقدار پاسخ یکی از دو حالت زیر خواهد بود:

پاسخ موفق

status: send ok

پاسخ ناموفق

status: send notok

نکته مهم

برای تشخیص موفقیت ارسال، کافی است بررسی کنید که پاسخ دریافتی شامل عبارت 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 است