اتصال NetBill — Provisioning

> version: 1.2 | last_updated: 2026-08-10 | audience: admin
> مستند رسمی (محلی): [`NetBill-WebService-Guide-V3.8.pdf`](./NetBill-WebService-Guide-V3.8.pdf)
> منبع ناشر: https://netbill.ir/site/docs/NetBill-WebService-Guide-V3.8.pdf

معرفی

ماژول `netbill` با **WebService رسمی NetBill v3.8** (قاصدک سامانه) یکپارچه می‌شود.

پروتکل: **HTTP GET** + پاسخ **XML**

آدرس پایه: `http://IP/netbill-holder/webservice/?admin=ADMIN_ID&method=...`

احراز هویت: پارامتر `admin` (= ADMIN_ID) — بدون Bearer/Basic

---

دریافت ADMIN_ID

وارد لایه **VISP** شوید

منو **Manage Visps** → روی **Login As** کلیک راست → **Copy Link Location**

عدد HASH داخل URL همان `admin_id` است

---

پیکربندی Tenant (سرور بیرونی)

**Provisioning → سرورهای بیرونی → ایجاد** با ماژول `netbill`

| فیلد config | مثال | توضیح |
|-------------|------|--------|
| `base_url` | `http://192.168.1.10` | IP/دامنه NetBill **بدون** مسیر webservice |
| `admin_id` | `abc123hash...` | HASH از Login As |
| `webservice_path` | `/netbill-holder/webservice/` | مسیر webservice |
| `timeout` | `30` | ثانیه |

Placeholderهای workflow از همین سرور:

`{{netbill_base_url}}` / `{{netbill_webservice_url}}` / `{{netbill_admin_id}}`

عملیات HTTP با `external_module_key=netbill` و `netbill_method` (مثلاً `userinfo`) URL را از سرور می‌سازد.

وضعیت‌های عملیاتی seedشده: [`netbill-workflow-actions.md`](./netbill-workflow-actions.md)

---

پیکربندی محصول

**ماژول:** `netbill`

**provisioning_config (نمونه):**

| فیلد | توضیح |
|------|--------|
| `service_group_id` | ID گروه سرویس (sid) |
| `default_status_id` | پیش‌فرض ایجاد: `1` (Not Used) سپس BSS با `enable_status_id=2` فعال می‌کند |
| `enable_status_id` / `suspend_status_id` | `2` / `101` |
| `username_type` | `mobile` / `msisdn` / `imsi` / `national_code` / `number` / `number_character` |
| `password_type` | `fixed` + `password_fixed` یا تصادفی |
| `credit` / `zero_volume` / `remove_gigboxes` | کردیت و تمدید |
| `max_sim_login` / `exp_day_after_1st_login` / `policy_id` | پارامترهای adduser/edituser V3.8 |
| `caller_id` / `voip_hotline` | اختیاری VoIP |
| `rx_rate` / `tx_rate` | `set_user_limitations` |
| `isg_quota` | `service_id:credit;...` → `add_isg_service_to_user` |
| `fair_policy_credit` | گیگ‌باکس موقت (`add_temp_credit_to_user`) |

> برای `msisdn` / `imsi` بسته LTE باید قبل از ایجاد کاربر تخصیص شود.

کدهای status_id (V3.8)

| مقدار | معنی |
|-------|------|
| 1 | Not Used |
| 2 | Enabled |
| 101 | Disabled |
| 102 | Expired |
| 1000 | Low Credit |

type در addcredit

| مقدار | معنی |
|-------|------|
| 8 | NotPaid Money |
| 9 | Paid Money |
| 10 | NotPaid → Paid |
| 11 | Bonus (Deposit) |

---

عملیات BSS → NetBill

| BSS | method | پارامترها |
|-----|--------|-----------|
| ایجاد | `adduser` | username, password, sid, status_id, mobile_no, phone_no, serial_no, expire_date, … |
| فعال‌سازی | `edituser` | username, status_id=2 |
| تعلیق | `edituser` | username, status_id=101 |
| حذف | `deleteuser` | username |
| تغییر پلن | `edituser` | username, sid |
| کردیت | `addcredit` | username, type, value, reset_* ، set_remained_to_zero |
| محدودیت سرعت | `set_user_limitations` | username, rx_rate, tx_rate |
| ISG | `add_isg_service_to_user` | username, service_id, credit |
| گیگ‌باکس | `show/edit/add/del_temp_credit_*` | … |
| همگام‌سازی | `userinfo` | username |
| قطع آنلاین | `disconnect_user` | username |
| تست اتصال | `check_admin` | — |

کلاینت BSS (`NetBillClient`) متدهای V3.8 را پوشش می‌دهد؛ فراخوانی آزاد: `callMethod($method, $params)`.

---

تست اتصال

Sandbox را خاموش کنید

**تست اتصال** در Filament

پاسخ موفق: `Admin is correct` + نام admin

---

Sandbox

تا زمان دریافت `admin_id` واقعی، Sandbox را **فعال** نگه دارید.

---

نمونه URL (مستند رسمی)

```
http://IP/netbill-holder/webservice/?admin=ADMIN_ID&method=adduser&username=ali&password=123456&sid=5&status_id=2&mobile_no=09121234567&phone_no=02112345678
```

پاسخ موفق:

```xml
<USER>
<result_id>0</result_id>
<result_description>Successfully added!</result_description>
<username>ali</username>
<password>123456</password>
<visp_service_group_id>5</visp_service_group_id>
</USER>
```

`result_id < 0` = خطا.