نمایش مبدأ برای راهنمای اتصال مرکز تلفن ایزابل و استریکس به حسابیکس


= راهنمای اتصال مرکز تلفن به حسابیکس (Hesabix Telephony Connector) =
این راهنما برای '''مدیران سیستم'''، '''مدیران تلفن''' و '''کاربران نهایی''' نوشته شده است. هدف آن توضیح سادهٔ نصب، پیکربندی و استفاده از کانکتور تلفنی حسابیکس روی سرور '''Issabel''' یا '''Asterisk''' است.

'''این راهنما برای توسعه‌دهندگان نیست.'''
----

== کانکتور چیست و چه کاری انجام می‌دهد؟ ==
'''Hesabix Telephony Connector''' یک برنامهٔ سبک است که روی '''سرور تلفن شما''' (Issabel/Asterisk) نصب می‌شود و آن را به '''حسابیکس''' وصل می‌کند.

=== بدون کانکتور ===

* حسابیکس نمی‌تواند تماس‌های ورودی/خروجی را ببیند
* Screen Pop، Click-to-Call و تاریخچه تماس کار نمی‌کند
* وضعیت مرکز تلفن در حسابیکس «آفلاین» می‌ماند

=== با کانکتور ===

* رویدادهای تماس از Asterisk به حسابیکس ارسال می‌شود
* حسابیکس می‌تواند دستور تماس (مثل برقراری تماس خروجی) را به سرور تلفن بفرستد
* اپراتورها در وب، موبایل و دسکتاپ می‌توانند:
** هنگام زنگ خوردن، '''اطلاعات تماس‌گیرنده''' را ببینند (Screen Pop)
** از روی پروفایل مشتری '''تماس خروجی''' بگیرند (Click-to-Call)
** '''تاریخچه تماس''' را ببینند
** وضعیت '''آنلاین/آفلاین''' مرکز تلفن را مشاهده کنند

=== نکته مهم درباره معماری ===
کانکتور روی '''سرور تلفن شما''' نصب می‌شود، نه روی سرور حسابیکس.
{|
|+نمای ساده اتصال
|'''کاربر (اپراتور)'''
|← →
|'''حسابیکس (ابر/سرور شما)'''
|-
|'''کانکتور'''
|← →
|'''Issabel / Asterisk (سرور تلفن)'''
|}
کانکتور فقط از سرور تلفن به سمت حسابیکس '''خروجی HTTPS''' می‌زند؛ معمولاً نیازی به باز کردن پورت ورودی روی فایروال سرور تلفن نیست.
----

== پیش‌نیازها ==

=== سخت‌افزار و شبکه ===

* یک سرور '''Issabel''' یا '''Asterisk''' فعال
* دسترسی '''root''' به سرور تلفن (با یا بدون دستور <code>sudo</code>)
* اتصال اینترنت از سرور تلفن به آدرس API حسابیکس (پورت ۴۴۳ / HTTPS)
* Asterisk AMI فعال (پورت پیش‌فرض: ۵۰۳۸)

=== نرم‌افزار ===
اسکریپت نصب در صورت نبود، این موارد را خودکار نصب می‌کند:

* Python 3
* rsync
* curl
* git

=== توزیع‌های پشتیبانی‌شده ===
{| class="wikitable"
!خانواده
!نمونه توزیع‌ها
!مدیر بسته
|-
|Debian
|Debian، Ubuntu
|<code>apt-get</code>
|-
|RHEL
|CentOS، Rocky، Alma، '''Issabel'''
|<code>yum</code> یا <code>dnf</code>
|}

=== دسترسی‌های لازم در حسابیکس ===
قبل از نصب کانکتور، در پنل حسابیکس این کارها انجام شود:

# افزونه '''تلفنی / Telephony''' برای کسب‌وکار فعال باشد
# یک '''مرکز تلفن (PBX)''' ساخته شود
# '''توکن Connector''' از تنظیمات مرکز تلفن کپی شود
# (در صورت نیاز) '''شناسه کسب‌وکار''' و '''شناسه مرکز تلفن''' یادداشت شود

----

== آماده‌سازی در حسابیکس (قبل از نصب) ==

=== گام ۱: فعال‌سازی افزونه ===

# وارد حسابیکس شوید
# به بخش '''مارکت‌پلیس / افزونه‌ها''' بروید
# افزونه تلفنی (Telephony) را برای کسب‌وکار خود فعال کنید

=== گام ۲: ساخت مرکز تلفن ===

# به بخش '''مرکز تلفن / Telephony''' بروید
# یک مرکز تلفن جدید بسازید (نام، توضیحات و …)
# نوع اتصال: '''Issabel / Asterisk''' (یا معادل آن در رابط کاربری)

=== گام ۳: دریافت اطلاعات اتصال ===
از صفحهٔ تنظیمات مرکز تلفن این موارد را یادداشت کنید:
{| class="wikitable"
!مورد
!توضیح
!مثال
|-
|آدرس API حسابیکس
|آدرس سرویس حسابیکس شما
|<code>https://hsxn.hesabix.ir</code>
|-
|شناسه کسب‌وکار (Business ID)
|عدد شناسه کسب‌وکار
|<code>12</code>
|-
|شناسه مرکز تلفن (PBX ID)
|عدد شناسه مرکز تلفن
|<code>3</code>
|-
|توکن Connector
|رشتهٔ امن اتصال
|<code>hsx_tel_...</code>
|}
'''هشدار امنیتی:''' توکن را مثل رمز عبور نگه دارید. در اختیار کسی قرار ندهید.
----

== نصب کانکتور ==
نصب روی '''سرور تلفن''' انجام می‌شود (SSH به Issabel/Asterisk).

=== روش پیشنهادی: نصب یک‌خطی ===
'''اگر سیستم شما <code>sudo</code> دارد''' (مثلاً Ubuntu):<syntaxhighlight lang="bash">
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | sudo bash
</syntaxhighlight>'''اگر <code>sudo</code> ندارید''' (مثلاً Debian یا Issabel با ورود مستقیم root):<syntaxhighlight lang="bash">
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | bash
</syntaxhighlight>

=== تغییر آدرس API هنگام نصب ===
پیش‌فرض آدرس API برابر <code>https://hsxn.hesabix.ir</code> است. اگر سرور اختصاصی دارید:<syntaxhighlight lang="bash">
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh \
  | HESABIX_API_URL=https://my-api.example.com bash
</syntaxhighlight>

=== مراحلی که اسکریپت خودکار انجام می‌دهد ===

# تشخیص سیستم‌عامل (Debian/Ubuntu یا Issabel/CentOS/RHEL)
# نصب پیش‌نیازها در صورت نیاز
# دانلود کانکتور از مخزن حسابیکس
# نصب دستور <code>hesabix-pbx</code> در سیستم
# اجرای '''ویزارد پیکربندی'''
# ثبت و فعال‌سازی سرویس <code>systemd</code>

=== مسیر نصب پیش‌فرض ===
<syntaxhighlight lang="text">
/opt/HesabixTelephonyConnector
</syntaxhighlight>
----

== ویزارد پیکربندی (اولین بار) ==
بعد از نصب، ویزارد از شما می‌پرسد:
{| class="wikitable"
!سؤال
!توضیح
!پیش‌فرض
|-
|آدرس API حسابیکس
|آدرس سرویس حسابیکس
|<code>https://hsxn.hesabix.ir</code>
|-
|شناسه کسب‌وکار
|Business ID از حسابیکس
|—
|-
|شناسه مرکز تلفن
|PBX ID از حسابیکس
|—
|-
|توکن Connector
|از تنظیمات مرکز تلفن
|—
|-
|آدرس AMI
|معمولاً همان سرور محلی
|<code>127.0.0.1</code>
|-
|پورت AMI
|پورت Asterisk Manager
|<code>5038</code>
|-
|کاربر AMI
|نام کاربری AMI
|<code>hesabix</code>
|-
|رمز AMI
|رمز کاربر AMI
|—
|-
|ساخت کاربر AMI؟
|آیا کانکتور کاربر را در <code>manager.conf</code> بسازد؟
|معمولاً <code>N</code> مگر مطمئن نباشید
|}
'''نکته:''' اگر Issabel از قبل کاربر AMI دارد، همان را وارد کنید. در غیر این صورت می‌توانید با پاسخ <code>y</code> اجازه دهید کانکتور کاربر را بسازد.

پیکربندی در این فایل ذخیره می‌شود:<syntaxhighlight lang="text">
/opt/HesabixTelephonyConnector/.env
</syntaxhighlight>
----

== تست اتصال ==
بعد از نصب، حتماً تست کنید:<syntaxhighlight lang="bash">
hesabix-pbx test
</syntaxhighlight>این دستور دو تست انجام می‌دهد:

# '''تست AMI''' — اتصال به Asterisk و ورود با کاربر AMI
# '''تست Heartbeat حسابیکس''' — ارسال سیگنال زنده به API حسابیکس

اگر هر دو موفق باشند، در حسابیکس وضعیت مرکز تلفن باید '''آنلاین (Online)''' شود.

برای مشاهده وضعیت کلی:<syntaxhighlight lang="bash">
hesabix-pbx status
</syntaxhighlight>
----

== دستورات روزمره (CLI) ==
همهٔ دستورات زیر روی '''سرور تلفن''' و با دسترسی root اجرا می‌شوند.
{| class="wikitable"
!دستور
!کاربرد
|-
|<code>hesabix-pbx status</code>
|نمایش وضعیت سرویس، سیستم‌عامل، API، AMI و …
|-
|<code>hesabix-pbx test</code>
|تست AMI و اتصال به حسابیکس
|-
|<code>hesabix-pbx configure</code>
|تغییر توکن، آدرس API، تنظیمات AMI
|-
|<code>hesabix-pbx start</code>
|شروع سرویس کانکتور
|-
|<code>hesabix-pbx stop</code>
|توقف سرویس
|-
|<code>hesabix-pbx restart</code>
|ری‌استارت سرویس
|-
|<code>hesabix-pbx update</code>
|به‌روزرسانی کانکتور از مخزن حسابیکس
|-
|<code>hesabix-pbx reinstall</code>
|نصب مجدد (فایل <code>.env</code> حفظ می‌شود)
|-
|<code>hesabix-pbx logs</code>
|مشاهده آخرین لاگ‌ها (پیش‌فرض ۸۰ خط)
|-
|<code>hesabix-pbx logs 200</code>
|مشاهده ۲۰۰ خط آخر لاگ
|-
|<code>hesabix-pbx follow</code>
|مشاهده زندهٔ لاگ (مثل <code>tail -f</code>)
|-
|<code>hesabix-pbx uninstall</code>
|حذف سرویس و دستور CLI
|-
|<code>hesabix-pbx help</code>
|نمایش راهنمای دستورات
|}

=== مثال: اجرا با sudo ===
<syntaxhighlight lang="bash">
sudo hesabix-pbx status
sudo hesabix-pbx test
sudo hesabix-pbx update
</syntaxhighlight>

=== مثال: اجرا بدون sudo (کاربر root) ===
<syntaxhighlight lang="bash">
hesabix-pbx status
hesabix-pbx test
hesabix-pbx update
</syntaxhighlight>
----

== به‌روزرسانی کانکتور ==
برای دریافت آخرین نسخه:<syntaxhighlight lang="bash">
hesabix-pbx update
</syntaxhighlight>این دستور:

* پیش‌نیازها را بررسی می‌کند
* فایل‌های جدید را دانلود می‌کند
* سرویس را ری‌استارت می‌کند
* فایل <code>.env</code> شما را '''حفظ''' می‌کند

بعد از به‌روزرسانی:<syntaxhighlight lang="bash">
hesabix-pbx status
hesabix-pbx test
</syntaxhighlight>
----

== تغییر تنظیمات بعد از نصب ==

=== تغییر توکن، API یا AMI ===
<syntaxhighlight lang="bash">
hesabix-pbx configure
hesabix-pbx restart
hesabix-pbx test
</syntaxhighlight>

=== موارد رایج تغییر ===

* '''توکن جدید''' بعد از لو رفتن توکن قبلی
* '''آدرس API''' بعد از تغییر دامنه حسابیکس
* '''رمز AMI''' بعد از تغییر در Asterisk

----

== پیکربندی دستی (بدون ویزارد) ==
اگر ترجیح می‌دهید فایل را مستقیم ویرایش کنید:<syntaxhighlight lang="bash">
cp /opt/HesabixTelephonyConnector/config.example.env /opt/HesabixTelephonyConnector/.env
nano /opt/HesabixTelephonyConnector/.env
hesabix-pbx restart
hesabix-pbx test
</syntaxhighlight>

=== نمونه محتوای فایل <code>.env</code> ===
<syntaxhighlight lang="ini">
HESABIX_API_URL=https://hsxn.hesabix.ir
HESABIX_BUSINESS_ID=1
HESABIX_PBX_ID=1
HESABIX_CONNECTOR_TOKEN=hsx_tel_replace_me
AMI_HOST=127.0.0.1
AMI_PORT=5038
AMI_USER=hesabix
AMI_SECRET=change_me
</syntaxhighlight>
----

== کاربرد برای کاربران حسابیکس ==
بعد از اتصال موفق، این امکانات (بسته به فعال بودن افزونه و دسترسی کاربر) در دسترس است:

=== برای اپراتور (فروش / پشتیبانی) ===

* '''Screen Pop:''' هنگام زنگ خوردن، نام مشتری، مانده حساب و اطلاعات مرتبط نمایش داده می‌شود
* '''Click-to-Call:''' از پروفایل مشتری می‌توان تماس خروجی گرفت
* '''تاریخچه تماس:''' مشاهده تماس‌های قبلی هر مشتری
* '''ثبت نتیجه تماس:''' یادداشت و پیگیری بعد از مکالمه

=== برای مدیر تلفن ===

* مشاهده وضعیت '''آنلاین/آفلاین''' مرکز تلفن
* نگاشت '''کاربر حسابیکس ↔ داخلی تلفن'''
* تنظیمات شناسایی شماره و رفتار Screen Pop

=== برای مدیر سیستم ===

* مانیتورینگ اتصال از طریق <code>hesabix-pbx status</code>
* بررسی لاگ‌ها با <code>hesabix-pbx logs</code>
* به‌روزرسانی و نگهداری با <code>hesabix-pbx update</code>

----

== عیب‌یابی (مشکلات رایج) ==

=== ۱. مرکز تلفن در حسابیکس آفلاین است ===

# روی سرور تلفن: <code>hesabix-pbx status</code>
# تست اتصال: <code>hesabix-pbx test</code>
# بررسی لاگ: <code>hesabix-pbx logs</code>
# مطمئن شوید توکن، Business ID و PBX ID درست است
# مطمئن شوید سرور تلفن به آدرس API دسترسی HTTPS دارد

=== ۲. تست AMI ناموفق است ===

* Asterisk در حال اجرا باشد
* پورت AMI (معمولاً ۵۰۳۸) باز باشد — فقط روی localhost کافی است
* کاربر و رمز AMI درست باشد
* در صورت نیاز: <code>asterisk -rx "manager reload"</code>

=== ۳. تست API حسابیکس ناموفق است ===

* آدرس <code>HESABIX_API_URL</code> را بررسی کنید (بدون اسلش اضافه در انتها)
* DNS و فایروال سرور تلفن را بررسی کنید
* توکن را در حسابیکس تجدید کنید و با <code>hesabix-pbx configure</code> وارد کنید

=== ۴. دستور <code>sudo</code> شناخته نمی‌شود ===
با کاربر root وارد شوید و دستور را بدون sudo اجرا کنید:<syntaxhighlight lang="bash">
hesabix-pbx status
</syntaxhighlight>

=== ۵. بعد از به‌روزرسانی مشکل پیش آمد ===
<syntaxhighlight lang="bash">
hesabix-pbx reinstall
hesabix-pbx test
</syntaxhighlight>

=== ۶. سرویس اجرا نمی‌شود ===
<syntaxhighlight lang="bash">
hesabix-pbx status
hesabix-pbx logs
systemctl status hesabix-telephony-connector
</syntaxhighlight>
----

== نکات امنیتی ==

* کانکتور فقط به حسابیکس '''خروجی HTTPS''' می‌زند — نیازی به باز کردن پورت ورودی روی اینترنت نیست
* پورت AMI (۵۰۳۸) را '''به اینترنت باز نکنید''' — فقط localhost یا شبکه داخلی
* فایل <code>.env</code> حاوی توکن و رمز AMI است؛ مجوز آن <code>600</code> است
* اگر توکن لو رفت:

## در حسابیکس توکن جدید بسازید
## روی سرور: <code>hesabix-pbx configure</code>
## سپس: <code>hesabix-pbx restart</code>

----

== حذف کانکتور ==
<syntaxhighlight lang="bash">
hesabix-pbx uninstall
</syntaxhighlight>در پایان از شما پرسیده می‌شود آیا فایل <code>.env</code> نگه داشته شود یا نه.

* '''نگه داشتن .env''' — برای نصب مجدد بعدی مفید است
* '''حذف کامل''' — همهٔ فایل‌ها پاک می‌شود

----

== سوالات متداول (FAQ) ==

=== آیا کانکتور روی سرور حسابیکس نصب می‌شود؟ ===
خیر. روی '''سرور Issabel/Asterisk''' نصب می‌شود.

=== آیا باید پورت جدیدی روی فایروال باز کنم؟ ===
معمولاً خیر. فقط خروجی HTTPS به حسابیکس لازم است.

=== آیا با FreePBX هم کار می‌کند؟ ===
اگر Asterisk AMI استاندارد داشته باشد، معمولاً بله. تمرکز رسمی روی '''Issabel''' است.

=== آدرس پیش‌فرض API چیست؟ ===
<code>https://hsxn.hesabix.ir</code>

=== چطور بفهمم همه‌چیز درست کار می‌کند؟ ===

# <code>hesabix-pbx test</code> هر دو تست را پاس کند
# در حسابیکس وضعیت مرکز تلفن «آنلاین» باشد
# یک تماس تست بگیرید و Screen Pop را در حسابیکس ببینید

----

== خلاصه دستورات پرکاربرد ==
<syntaxhighlight lang="bash">
# نصب (یک‌خطی)
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | bash

# وضعیت و تست
hesabix-pbx status
hesabix-pbx test

# تغییر تنظیمات
hesabix-pbx configure
hesabix-pbx restart

# به‌روزرسانی
hesabix-pbx update

# لاگ
hesabix-pbx logs
hesabix-pbx follow
</syntaxhighlight>
----