نرم‌افزار هُما

بازگشت به فهرست

سرویس API پیامدهی

REST API

API — ارسال پیام تکی (Single SMS)

این متد صرفاً برای ارسال پیامک تکی کاربرد دارد.

برای اتصال جدید، از درگاه خودِ هما استفاده کنید — نه این سرویس.

درگاه توکن‌محور هما

https://www.HomaCRM.com/api/v1/external/messaging/send

  • احراز هویت با توکن API (پنل Token, API & MCP Server) — بدون نیاز به رمز پرتال
  • ن‌ک بخش «اتصال سایر نرم‌افزارها» در همین راهنما

سرویس زیر (api.homais.com) فقط برای سازگاری با اتصال‌های قدیمی مستند شده است و توکن API را نمی‌پذیرد؛ احراز هویتش با نام کاربری و رمز عبور پرتال است.

Endpoint

https://api.homais.com/services/messaging/sms/api/sendMessage/direct/

GET — نمونه URL

https://api.homais.com/services/messaging/sms/api/sendMessage/direct/?username=PORTAL_USERNAME&password=PORTAL_PASSWORD&PortalCode=ZZZZ&mobile=09121234567&message=textMessage&reference=YOUR_LINE_REFERENCE

نکات مهم

  • مقدار بازگشتی: عدد بزرگ‌تر از ۱۰۰۰ = موفق (کد رهگیری)؛ عدد مثبت کوچک‌تر از ۱۰۰۰ یا منفی = خطا
  • می‌توانید URL را مستقیماً در مرورگر برای تست باز کنید
  • کدهای خطا در بخش «جدول کدهای بازگشتی» آمده است
  • ServerType را می‌توانید 1، 4 یا 6 هم بگذارید؛ در این صورت از شماره شخصی ارسال می‌شود و ارسال به لیست سیاه غیرفعال می‌شود

API — ارسال OTP

ارسال رمز یکبار مصرف (۶ رقمی)؛ پس از ارسال، رمز تولیدشده نیز در پاسخ برمی‌گردد.

برای اتصال جدید، از درگاه خودِ هما استفاده کنید — نه این سرویس.

درگاه توکن‌محور هما

https://www.HomaCRM.com/api/v1/external/messaging/send

  • احراز هویت با توکن API (پنل Token, API & MCP Server) — بدون نیاز به رمز پرتال
  • ن‌ک بخش «اتصال سایر نرم‌افزارها» در همین راهنما

سرویس زیر (api.homais.com) فقط برای سازگاری با اتصال‌های قدیمی مستند شده است و توکن API را نمی‌پذیرد؛ احراز هویتش با نام کاربری و رمز عبور پرتال است.

Endpoint

https://api.homais.com/services/messaging/sms/api/sendMessage/OTP/

GET — نمونه URL

https://api.homais.com/services/messaging/sms/api/sendMessage/OTP/?username=PORTAL_USERNAME&password=PORTAL_PASSWORD&PortalCode=ZZZZ&mobile=09121234567&message=textMessage&reference=YOUR_LINE_REFERENCE

  • پاسخ موفق: عدد بزرگ‌تر از ۱۰۰۰؛ خطا: عدد کوچک‌تر از ۱۰۰۰ یا منفی
  • پارامتر ServerType=100 برای ارسال عمومی/لیست سیاه توصیه می‌شود

API — ارسال با GET/POST (بدون QueryString)

همان endpoint ارسال تکی؛ تفاوت در این است که پارامترها را در body درخواست POST (یا GET با body) بفرستید، نه در QueryString.

Endpoint

https://api.homais.com/services/messaging/sms/api/sendMessage/direct/

ضروری فیلد ضروری اختیاری فیلد اختیاری
پارامتر نوع توضیح
usernameضرورینام کاربری پرتال (این سرویس توکن API را نمی‌پذیرد)
passwordضروریرمز عبور همان کاربر — خالی بماند خطای missing_credentials می‌دهد
PortalCodeضروریکد پرتال
mobileضروریشماره موبایل (با 09)
messageضروریمتن پیام
referenceضروریشمارهٔ مرجعِ خطِ فرستندهٔ خودتان (از پنل). پارامترِ قدیمیِ ServerType هم همین را می‌گیرد، ولی اگر هر دو را بفرستید reference مقدم است. عددی که مرجعِ هیچ خطی از شما نباشد — مثلاً 100 — چیزی ارسال نمی‌کند.

نکات

  • برای اتصال نرم‌افزارهای حسابداری از بخش «اتصال سایر نرم‌افزارها» استفاده کنید: نام کاربری = توکن API، کد پرتال = پارامتر PortalCode.
  • اتصال مستقیم فقط وقتی ممکن است که نرم‌افزار اجازه تعریف URL و پارامترهای دلخواه را بدهد؛ در غیر این صورت افزونه/واسط اختصاصی لازم است.
  • ServerType=100 برای ارسال عمومی و OTP (لیست سیاه مخابرات) توصیه می‌شود.
  • پاسخ موفق: عدد بزرگ‌تر از ۱۰۰۰؛ هر عدد دیگر کد خطاست.
  • برای پیام حاوی لینک یا ارسال از شماره عمومی، پروفایل WhoIS باید تکمیل و تأیید شده باشد.
  • برای تست سریع REST API، URL را با پارامترها در مرورگر باز کنید.
  • در صورت خطا، کد بازگشتی و ServerType را در تیکت پشتیبانی ذکر کنید.