سرویس API پیامدهی
اتصال سایر نرمافزارها
۱) معرفی API
API سادهٔ HTTP برای اتصال نرمافزارهای حسابداری و ERP (هلو، پارمیس، محک، نگین و …) به سرویس پیامک هُما. اگر نرمافزار URL و پارامترها را قابل تنظیم بدهد، اتصال مستقیم انجام میشود.
آدرس API (URL)
https://www.HomaCRM.com/api/v1/external/messaging/gateway
هر دو روش GET و POST پشتیبانی میشوند.
۲) دریافت توکن API
توکن API از پنل Token, API & MCP Server گرفته میشود — همان توکن برای SOAP (UserName)، REST (username)، MCP و درگاه خارجی.
- با حساب مدیر اصلی (Main Admin) وارد شوید.
- داخل پرتال: بخش مدیریت کاربران را باز کنید و دکمهٔ «توکنها» را بزنید.
- کنسول پرتالها: کنار کد پرتال، روی آیکون توکن API (
</>) کلیک کنید. - در پنجرهٔ بازشده، توکن اصلی را نمایش دهید و کپی کنید — یا از بخش Token list یک توکن ثانویه بسازید.
- کد پرتال را هم یادداشت کنید (در همین پنجره یا کنار نام پرتال در کنسول).
توکن را محرمانه نگه دارید. با «رفرش توکن اصلی»، همهٔ اتصالهای قبلی قطع میشوند.
۳) پارامترهای درگاه و نامهای معادل
نام پارامترها حساس به بزرگی/کوچکی حروف نیست و برای هر فیلد چند نام معادل (alias) پذیرفته میشود تا تنظیم در هر نرمافزاری آسان باشد.
| پارامتر | نامهای معادل | نوع | توضیح |
|---|---|---|---|
| username | user, uname | ضروری | توکن API |
| to | mobile, recipient, receiver, phone | ضروری | شمارهٔ گیرنده؛ به 09XXXXXXXXX نرمال میشود |
| text | message, msg, body, content | ضروری | متن پیامک (حداکثر ۶۰۰ کاراکتر) |
| password | pass, apikey, api_key, apiKey, key, token | اختیاری | توکن API (اگر نرمافزار فیلد جداگانه برای رمز دارد) |
| PortalCode | portalcode, portal_code | اختیاری | کد پرتال، مثلاً 10003385 |
| ServerType | servertype, server_type | اختیاری | نوع سرور؛ مثلاً 100 برای ارسال عمومی/لیست سیاه |
| from | sender, line, number, senderid, sender_id | اختیاری | شمارهٔ خط فرستنده (در صورت خالی، خط پیشفرض پرتال) |
| format | output, response | اختیاری | text (پیشفرض) یا json |
۴) نگاشت فیلدها و احراز هویت
در فیلدهای ورود نرمافزار، مقادیر زیر را وارد کنید:
| فیلد در نرمافزار | پارامتر درگاه | مقدار | نوع |
|---|---|---|---|
| نام کاربری (UserName) | username | توکن API | ضروری |
| شماره گیرنده (To) | to | موبایل گیرنده | ضروری |
| متن پیام (Message) | text | متن پیامک | ضروری |
| کد پرتال (PortalCode) | PortalCode | کد پرتال، مثلاً 10003385 | اختیاری |
| نوع سرور (ServerType) | ServerType | مثلاً 100 | اختیاری |
توکن را در فیلد username قرار دهید و کد پرتال را در پارامتر PortalCode بفرستید. درگاه توکن را از username، password، apikey یا هدر Authorization/X-API-Key هم میپذیرد.
۵) هلو (Holoo) — نسخههای دارای سرویسدهنده دلخواه
در نسخههایی از هلو که امکان تعریف سرویسدهنده پیامک یا وبسرویس دلخواه دارند، مسیر معمول این است: تنظیمات مدیریتی ← تنظیمات سرویسدهنده. روی علامت «+» بزنید و یک درگاه جدید بسازید؛ سپس از دکمهٔ «چرخدندهٔ تنظیمات»، نام پارامترها را تعریف کنید.
| فیلد | مقدار | نوع |
|---|---|---|
| آدرس سایت (URL) | https://www.HomaCRM.com/api/v1/external/messaging/gateway | ضروری |
| نام کاربری | توکن API | ضروری |
| UserName → پارامتر | username | ضروری |
| To → پارامتر | to | ضروری |
| Message → پارامتر | text | ضروری |
| نام پنل | HomaCRM (دلخواه) | اختیاری |
| PortalCode → پارامتر | PortalCode | اختیاری |
| ServerType → پارامتر | ServerType | اختیاری |
در پایان، در «نحوهٔ ارسال»، گزینهٔ ارسال اینترنتی/وبسرویس را انتخاب و ذخیره کنید.
اگر نسخهٔ هلو فقط فهرست سرویسدهندههای ثابت را نشان میدهد و دکمهٔ تعریف URL یا پارامتر ندارد، اتصال مستقیم با این درگاه ممکن نیست و باید افزونه/واسط اختصاصی بررسی شود.
۶) جدول سازگاری نرمافزارها
ساختار اتصال در نسخههای مختلف هر نرمافزار ممکن است فرق کند. جدول زیر کمک میکند سریع تشخیص دهید اتصال مستقیم با URL کافی است یا باید افزونه/واسط جداگانه بررسی شود.
| نرمافزار | وضعیت پیشنهادی | روش اتصال | توضیح |
|---|---|---|---|
| هلو / Holoo | قابل تست مستقیم در نسخههای دارای سرویسدهنده دلخواه | وبسرویس دلخواه | اگر URL و پارامترها قابل تنظیم باشند، همین درگاه کافی است. |
| هلو APEX | نیازمند بررسی نسخه | وبسرویس دلخواه یا واسط | اگر فقط سرویسدهندههای ثابت دارد، نیازمند واسط اختصاصی است. |
| پارمیس / Parmis | ماژول/سامانه پیامکی رسمی دارد | ماژول پیامک یا URL دلخواه | اتصال مستقیم فقط وقتی ممکن است که پنل یا وبسرویس دلخواه بپذیرد. |
| محک / Mahak | افزونه پیامکرسان رسمی دارد | افزونه یا URL دلخواه | اگر افزونه فقط سرویسدهنده ثابت دارد، HomaCRM باید به فهرست افزوده شود یا واسط نوشته شود. |
| نگین / Negin | وابسته به محصول دقیق | وبسرویس دلخواه | بهدلیل تنوع نرمافزارهای با نام نگین، نام کامل محصول و نسخه باید بررسی شود. |
| دشت همکاران سیستم | زیرسیستم پیامک رسمی دارد | زیرسیستم پیامک یا واسط | اتصال مستقیم فقط در صورت وجود URL دلخواه در زیرسیستم/افزونه ممکن است. |
| سپیدار | نیازمند بررسی افزونه | افزونه/واسط اختصاصی | در بسیاری از نصبها سرویسدهندهها ثابت هستند و URL دلخواه آزاد نیست. |
| راهکاران همکاران سیستم | نیازمند پروژه واسط | API/Integration اختصاصی | برای ERP سازمانی، تنظیم ساده URL معمولاً کافی نیست. |
| شایگان، قیاس، فرداد، آرین سیستم، تدبیر، پیوست، رافع | وابسته به نسخه و ماژول پیامک | وبسرویس دلخواه یا واسط | اگر فیلد URL و پارامترهای to/text قابل تنظیم باشند، اتصال مستقیم است. |
| حسابفا، چرتکه و نرمافزارهای ابری | معمولاً API محور یا محدود به سرویس داخلی | API/واسط | در نرمافزارهای ابری، امکان انتخاب پنل پیامک دلخواه باید از تنظیمات همان سرویس بررسی شود. |
۷) پارمیس / محک / نگین و سایر نرمافزارها
در پارمیس و محک، ابتدا بررسی کنید نسخهٔ نصبشده از «پنل/وبسرویس دلخواه» پشتیبانی میکند یا فقط ماژول و سرویسدهندههای رسمی خود نرمافزار را میپذیرد. اگر گزینهٔ «وبسرویس دلخواه/عمومی» وجود دارد، مقادیر زیر را وارد کنید:
| فیلد | مقدار | نوع |
|---|---|---|
| آدرس وبسرویس (URL) | https://www.HomaCRM.com/api/v1/external/messaging/gateway | ضروری |
| نام کاربری | توکن API | ضروری |
| پارامتر گیرنده | to | ضروری |
| پارامتر متن | text | ضروری |
| نوع سرور ServerType | ServerType | اختیاری |
| کد پرتال PortalCode | PortalCode | اختیاری |
نکته: پارمیس و محک هر دو در منابع رسمی خود ماژول/افزونه پیامکی معرفی کردهاند. بنابراین اگر در نسخهٔ مشتری فقط همان افزونه فعال است و URL دلخواه ندارد، اتصال مستقیم با این درگاه انجام نمیشود و باید افزودن HomaCRM به افزونه یا ساخت واسط اختصاصی بررسی شود.
۸) وبسرویس عمومی و نمونهٔ آماده (curl)
هر نرمافزاری که امکان تعریف «آدرس + پارامترهای دلخواه» را دارد، میتواند با الگوی زیر متصل شود:
الگوی GET
https://www.HomaCRM.com/api/v1/external/messaging/gateway?username={token}&PortalCode={portalCode}&ServerType={serverType}&to={mobile}&text={message}
نمونهٔ GET با curl:
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/gateway" \
--data-urlencode "username=YOUR_TOKEN" \
--data-urlencode "PortalCode=10003385" \
--data-urlencode "ServerType=100" \
--data-urlencode "to=09129876543" \
--data-urlencode "text=سلام، سفارش شما ثبت شد"نمونهٔ POST با curl:
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/gateway" \
-d "username=YOUR_TOKEN" \
-d "PortalCode=10003385" \
-d "ServerType=100" \
-d "to=09129876543" \
-d "text=کد تأیید شما: 847291"قالب پاسخ:
- پیشفرض (متن ساده): موفقیت = یک «شناسهٔ پیام» مثبت؛ خطا = مقدار
0یا منفی. - با افزودن
?format=jsonپاسخ بهصورت JSON استاندارد برمیگردد.
{
"success": true,
"data": { "messageId": 184920315, "recipient": "09129876543", "status": "queued", "creditUsed": 1 },
"meta": { "requestId": "req_7f3a9c21b4e8" }
}۹) کدهای پاسخ متن ساده و محدودیتها
در حالت پیشفرض (متن ساده)، درگاه همیشه با HTTP 200 پاسخ میدهد و نتیجه در بدنه است:
| مقدار | شرح |
|---|---|
| عدد مثبت | موفق — شناسهٔ پیام (کد رهگیری) |
| 0 | خطای احراز هویت (توکن نامعتبر/نبود توکن) |
| -2 | یکی از فیلدهای لازم (to/text) ارسال نشده |
| -4 | شمارهٔ گیرنده نامعتبر است |
| -1 | خطای ارسال (برای جزئیات از ?format=json استفاده کنید) |
محدودیتها:
- سپیدار / دشت / راهکاران همکاران سیستم: معمولاً با زیرسیستم، افزونه یا API اختصاصی کار میکنند. اتصال مستقیم فقط وقتی ممکن است که همان افزونه گزینهٔ URL دلخواه داشته باشد.
- پارمیس و محک: ماژول/افزونه پیامکی رسمی دارند؛ اگر نسخهٔ مشتری سرویسدهنده دلخواه را باز نکند، باید افزونه/واسط اختصاصی بررسی شود.
- نرمافزارهای صرفاً SOAP با این درگاه (REST/HTTP) سازگار نیستند؛ برای آنها از بخش «وبسرویس SOAP» همین راهنما استفاده کنید.
نکات
- برای اتصال نرمافزارهای حسابداری از بخش «اتصال سایر نرمافزارها» استفاده کنید: نام کاربری = توکن API، کد پرتال = پارامتر PortalCode.
- اتصال مستقیم فقط وقتی ممکن است که نرمافزار اجازه تعریف URL و پارامترهای دلخواه را بدهد؛ در غیر این صورت افزونه/واسط اختصاصی لازم است.
- ServerType=100 برای ارسال عمومی و OTP (لیست سیاه مخابرات) توصیه میشود.
- پاسخ موفق: عدد بزرگتر از ۱۰۰۰؛ هر عدد دیگر کد خطاست.
- برای پیام حاوی لینک یا ارسال از شماره عمومی، پروفایل WhoIS باید تکمیل و تأیید شده باشد.
- برای تست سریع REST API، URL را با پارامترها در مرورگر باز کنید.
- در صورت خطا، کد بازگشتی و ServerType را در تیکت پشتیبانی ذکر کنید.