سرویس API پیامدهی
دریافت پیامک
دریافت پیامک — Relay Service
برای دریافت ترافیک ورودی پیامک روی URL خود، یک endpoint بسازید و پارامترهای زیر را بپذیرید:
فرمت callback
yourURL/?portalcode=$value&reference=$value&smsNumber=$value&from=$value&body=$value
| پارامتر | نوع | توضیح |
|---|---|---|
| portalcode | ضروری | کد پرتال |
| reference | ضروری | نوع مرجع شماره دریافت‌کننده |
| smsNumber | ضروری | شماره دریافت‌کننده |
| from | ضروری | شماره موبایل فرستنده |
| body | ضروری | متن پیامک |
به محض دریافت پیامک، علاوه بر ذخیره در Inbox سیستم، یک نسخه به URL شما POST/GET می‌شود.
تنظیم URL در هُما:
- تنظیمات سیستم → تب «تنظیمات پایه»
- SYSTEM REGISTRY
- جستجوی
MODULES_SMS_RELAY_FORWARDING_URL - در Value 1 آدرس مطلق URL را وارد کنید (بدون پارامتر اضافه) — مثال:
http://relay.example.com/Relay - ذخیره و تست
ارسال پیامک ورودی به هُما — و توکن امنیتی:
اگر سامانهٔ پیامکی شما (مثلاً پیام‌گستر) پیامک‌های دریافتی را به یک URL می‌فرستد، آدرس زیر را در پنل آن سامانه ثبت کنید:
آدرس دریافت
https://<آدرس پرتال شما>/api/public/sms/relay?from=$value&to=$value&text=$value&token=$value
نام پارامترها باید دقیقاً from و to و text باشد. اگر سامانهٔ شما متن پیام را با نام دیگری می‌فرستد (مثلاً msg)، در پنل خودش قابل تغییر است.
توکن: چون این آدرس عمومی است، برای هر پرتال یک توکن اختصاصی صادر می‌شود تا کسی نتواند با دانستن شمارهٔ خط شما پیامک ورودی جعلی ثبت کند. تنظیمش از همان مسیر SYSTEM REGISTRY با کلید MODULES_SMS_RELAY_TOKEN است؛ مقدارش را در انتهای آدرس بالا به‌جای $value بگذارید.
در دورهٔ گذار، آدرس‌های بدون توکن هم هنوز کار می‌کنند تا اتصال‌های فعلی قطع نشود؛ ولی توکن غلط از همین حالا رد می‌شود. توصیه می‌شود توکن را زودتر تنظیم کنید.
نکات
- برای اتصال نرم‌افزارهای حسابداری از بخش «اتصال سایر نرم‌افزارها» استفاده کنید: نام کاربری = توکن API، کد پرتال = پارامتر PortalCode.
- اتصال مستقیم فقط وقتی ممکن است که نرم‌افزار اجازه تعریف URL و پارامترهای دلخواه را بدهد؛ در غیر این صورت افزونه/واسط اختصاصی لازم است.
- ServerType=100 برای ارسال عمومی و OTP (لیست سیاه مخابرات) توصیه می‌شود.
- پاسخ موفق: عدد بزرگ‌تر از ۱۰۰۰؛ هر عدد دیگر کد خطاست.
- برای پیام حاوی لینک یا ارسال از شماره عمومی، پروفایل WhoIS باید تکمیل و تأیید شده باشد.
- برای تست سریع REST API، URL را با پارامترها در مرورگر باز کنید.
- در صورت خطا، کد بازگشتی و ServerType را در تیکت پشتیبانی ذکر کنید.