====== MBLibExternal_APIUserManager ======

API-модуль управления абонентами MikBiLL. Позволяет создавать абонентов, получать их данные и обновлять информацию через HTTP-запросы.

**Версия:** 1.0.0\\
**Дата:** 2026-04-14

----

===== Настройка =====

==== Системные опции ====

Перед использованием API необходимо настроить системные опции в админ-панели MikBiLL (префикс ''usermanager_''):

^ Опция ^ Описание ^
| ''usermanager_on'' | Включение API (''1'' — включено, ''0'' — выключено) |
| ''usermanager_key'' | API-ключ для авторизации запросов |
| ''usermanager_network'' | Список разрешённых IP-адресов/подсетей для доступа к API |

==== Формат запроса ====

Все запросы передаются через массив ''$inputData'' с обязательными полями:

^ Параметр ^ Описание ^
| ''key'' | API-ключ (должен совпадать с ''usermanager_key'') |
| ''request'' | Название вызываемого метода |

==== Валидация ====

При каждом запросе выполняются проверки в следующем порядке:

  - **IP-адрес** — клиентский IP должен входить в список разрешённых (''usermanager_network'').
  - **Статус API** — опция ''usermanager_on'' должна быть равна ''1''.
  - **API-ключ** — параметр ''key'' должен совпадать с ''usermanager_key''.
  - **Наличие метода** — параметр ''request'' должен быть указан и соответствовать одному из поддерживаемых методов.

----

===== Коды ошибок =====

^ Код ^ Описание ^
| 0 | Success |
| 1 | API not enable |
| 2 | Wrong API key |
| 3 | Bad request (не указан ''request'') |
| 4 | Unknown request (неизвестный метод) |
| 5 | Access denied from your IP |
| 6 | Missing required parameter |
| 7 | User not found |
| 8 | Login already exists |
| 9 | Password not unique |
| 10 | No free IP in sector / ошибка создания |
| 11 | Connection template not found |
| 12 | Update failed |

Формат ответа при ошибке:

<code json>
{
    "error": "Текст ошибки",
    "error_code": 2
}
</code>

----

===== Методы API =====

==== get_supported_method_list ====

Возвращает список всех поддерживаемых методов API.

**Параметры:** нет (только ''key'' и ''request'')

**Ответ:**

<code json>
{
    "get_supported_method_list": { "comment": "Return Supported Method List" },
    "get_api_information": { "comment": "Return API Version" },
    "create_user": { "comment": "Create new subscriber by connection template" },
    "get_user_data": { "comment": "Get subscriber data by uid" },
    "update_user": { "comment": "Update subscriber data" }
}
</code>

----

==== get_api_information ====

Возвращает версию и дату API.

**Параметры:** нет

**Ответ:**

<code json>
{
    "version": "1.0.0",
    "date": "2026-04-14"
}
</code>

----

==== create_user ====

Создание нового абонента по шаблону подключения. Аналог ''createabonentfromconnectiontemplateExtjs''.

При создании автоматически:

  * списывается абонплата (если положена);
  * подключаются базовые услуги тарифа.

=== Обязательные параметры ===

^ Параметр ^ Тип ^ Описание ^
| ''connectiontemplateid'' | int | ID шаблона подключения |
| ''user'' | string | Логин абонента |
| ''password'' | string | Пароль абонента |
| ''gid'' | int | ID тарифа |

=== Необязательные параметры ===

^ Параметр ^ Тип ^ Описание ^
| ''fio'' | string | ФИО абонента |
| ''phone'' | string | Телефон |
| ''email'' | string | Email |
| ''houseid'' | int | ID дома |
| ''app'' | string | Квартира |
| ''porch'' | int | Подъезд |
| ''floor'' | int | Этаж |
| ''sectorid'' | int | ID сектора (если не задан в шаблоне) |
| ''usersgroupid'' | int | ID группы абонентов (субпровайдер) |
| ''is_legal'' | int | Юридическое лицо (''1'' — да, ''0'' — нет) |
| ''use_installments'' | int | Рассрочка (''1'' — да, ''0'' — нет) |
| ''custom_user_price'' | float | Индивидуальная цена пакета |
| ''custom_user_rate_down'' | float | Индивидуальная скорость загрузки |
| ''custom_user_rate_up'' | float | Индивидуальная скорость отдачи |

=== Логика обработки ===

  * Если логин уже занят и включена сисопция ''autogen_login_do'', логин генерируется автоматически.
  * Если включена сисопция ''generate_pwd_unique'', пароль проверяется на уникальность.

=== Успешный ответ ===

<code json>
{
    "result": "ok",
    "uid": 12345,
    "login": "subscriber01"
}
</code>

=== Пример запроса ===

<code>
https://admin.mikbill.pro/json/index/usermanager?key=MY_API_KEY&request=create_user&connectiontemplateid=1&user=newuser&password=pass123&gid=5&fio=Иванов Иван&phone=0501234567
</code>

----

==== get_user_data ====

Получение полных данных абонента по ''uid''. Аналог ''getuserdatambpAjax''.

=== Параметры ===

^ Параметр ^ Тип ^ Описание ^
| ''uid'' | int | **Обязательный.** ID абонента |

=== Возвращаемые данные ===

== Основная информация ==

^ Поле ^ Тип ^ Описание ^
| ''uid'' | int | ID абонента |
| ''login'' | string | Логин |
| ''fio'' | string | ФИО |
| ''state_id'' | int | Статус: ''1'' — активен, ''2'' — заблокирован, ''3'' — заморожен, ''4'' — удалён |
| ''flag_corporate'' | int | Юридическое лицо (''1''/''0'') |
| ''deposit'' | float | Баланс |
| ''credit'' | float | Кредит |
| ''blocked'' | int | Флаг блокировки |
| ''user_installed'' | int | Установлен ли абонент |

== Контактные данные ==

^ Поле ^ Тип ^ Описание ^
| ''phone'' | string | Телефон |
| ''mob_tel'' | string | Мобильный телефон |
| ''sms_tel'' | string | Телефон для SMS |
| ''email'' | string | Email |

== Тариф ==

^ Поле ^ Тип ^ Описание ^
| ''gid'' | int | ID текущего тарифа |
| ''tariff_name'' | string | Название текущего тарифа |
| ''gidd'' | int | ID следующего тарифа (''0'' — не назначен) |
| ''tariff_next_name'' | string | Название следующего тарифа |
| ''speed_rate'' | string | Скорость тарифа |
| ''speed_burst'' | string | Burst-скорость |
| ''discount'' | mixed | Значение скидки |

== Договор ==

^ Поле ^ Тип ^ Описание ^
| ''date_connect'' | string | Дата подключения |
| ''numdogovor'' | string | Номер договора |
| ''date_contract'' | string | Дата договора |

== Адрес ==

^ Поле ^ Тип ^ Описание ^
| ''houseid'' | int | ID дома |
| ''house'' | string | Дом |
| ''lane'' | string | Улица |
| ''settlementname'' | string | Населённый пункт |
| ''app'' | string | Квартира |
| ''porch'' | int | Подъезд |
| ''floor'' | int | Этаж |
| ''address'' | string | Полный адрес (текстовое поле) |

== Сеть ==

^ Поле ^ Тип ^ Описание ^
| ''sectorid'' | int | ID сектора |
| ''sector'' | string | Название сектора |
| ''local_ip'' | string | Локальный IP |
| ''local_mac'' | string | MAC-адрес |
| ''framed_ip'' | string | Framed IP |
| ''swid'' | int | ID коммутатора |
| ''switchname'' | string | Название коммутатора |
| ''switchport'' | int | Порт коммутатора |

== Статус и группа ==

^ Поле ^ Тип ^ Описание ^
| ''online'' | int | Онлайн-статус (''1''/''0'') |
| ''usersgroupid'' | int | ID группы абонентов |

== Дополнительно ==

^ Поле ^ Тип ^ Описание ^
| ''comment'' | string | Комментарий |
| ''inn'' | string | ИНН |
| ''date_birth'' | string | Дата рождения |
| ''passportserie'' | string | Серия паспорта |
| ''passportpropiska'' | string | Прописка по паспорту |
| ''passportgdevidan'' | string | Кем выдан паспорт |
| ''custom_fields'' | object | Все кастомные поля (ключ-значение) |

=== Пример ответа ===

<code json>
{
    "uid": 12345,
    "login": "subscriber01",
    "fio": "Иванов Иван Иванович",
    "state_id": 1,
    "flag_corporate": 0,
    "deposit": 150.50,
    "credit": 0,
    "gid": 5,
    "tariff_name": "Турбо 100",
    "gidd": 0,
    "tariff_next_name": "",
    "phone": "0501234567",
    "mob_tel": "",
    "sms_tel": "0501234567",
    "email": "user@example.com",
    "date_connect": "2024-01-15",
    "numdogovor": "D-12345",
    "date_contract": "2024-01-15",
    "blocked": 0,
    "user_installed": 1,
    "houseid": 42,
    "house": "15",
    "lane": "ул. Центральная",
    "settlementname": "г. Киев",
    "app": "101",
    "porch": 2,
    "floor": 5,
    "address": "",
    "sectorid": 3,
    "sector": "Сектор-1",
    "local_ip": "10.0.0.15",
    "local_mac": "AA:BB:CC:DD:EE:FF",
    "framed_ip": "192.168.1.15",
    "swid": 7,
    "switchname": "SW-Main-01",
    "switchport": 12,
    "speed_rate": "100M/100M",
    "speed_burst": "",
    "online": 1,
    "usersgroupid": 0,
    "comment": "",
    "inn": "",
    "date_birth": "1990-05-20",
    "discount": 0,
    "passportserie": "",
    "passportpropiska": "",
    "passportgdevidan": "",
    "custom_fields": {
        "ext_legal_person": "0",
        "ext_date_fiz_contract_conclusion": "2024-01-15"
    }
}
</code>

----

==== update_user ====

Обновление данных абонента. Аналог ''updateuserExtjs''.

=== Обязательные параметры ===

^ Параметр ^ Тип ^ Описание ^
| ''uid'' | int | ID абонента |

Помимо ''uid'', необходимо передать хотя бы одно поле для обновления.

=== Поля, доступные для обновления ===

== Основные ==

^ Поле ^ Тип ^ Описание ^
| ''fio'' | string | ФИО |
| ''phone'' | string | Телефон |
| ''mob_tel'' | string | Мобильный телефон |
| ''sms_tel'' | string | Телефон для SMS |
| ''email'' | string | Email |
| ''password'' | string | Пароль |
| ''user'' | string | Логин |
| ''gid'' | int | ID тарифа |
| ''deposit'' | float | Баланс |
| ''credit'' | float | Кредит |
| ''blocked'' | int | Флаг блокировки |

== Адрес ==

^ Поле ^ Тип ^ Описание ^
| ''houseid'' | int | ID дома |
| ''app'' | string | Квартира |
| ''porch'' | int | Подъезд |
| ''floor'' | int | Этаж |
| ''address'' | string | Адрес (текст) |

== Сеть ==

^ Поле ^ Тип ^ Описание ^
| ''sectorid'' | int | ID сектора |
| ''swid'' | int | ID коммутатора |
| ''switchport'' | int | Порт коммутатора |
| ''local_ip'' | string | Локальный IP |
| ''local_mac'' | string | MAC-адрес |
| ''framed_ip'' | string | Framed IP |

== Прочее ==

^ Поле ^ Тип ^ Описание ^
| ''prim'' | string | Комментарий |
| ''numdogovor'' | string | Номер договора |
| ''date_abonka'' | string | Дата начала абонплаты |
| ''passportserie'' | string | Серия паспорта |
| ''passportpropiska'' | string | Прописка |
| ''passportgdevidan'' | string | Кем выдан паспорт |
| ''inn'' | string | ИНН |
| ''user_installed'' | int | Установлен |
| ''date_birth'' | string | Дата рождения |

== Кастомные поля ==

Любые поля с префиксом ''ext_'', например:

^ Поле ^ Описание ^
| ''ext_date_fiz_contract_conclusion'' | Дата заключения договора |
| ''ext_legal_person'' | Юридическое лицо (''1''/''0'') |
| ''ext_gender'' | Пол |

=== Ошибки обновления ===

Метод ''updateUser'' может вернуть дополнительные коды ошибок:

^ Код ^ Описание ^
| 1 | Login already exists |
| 2 | No free IP in sector |
| 3 | Invalid MAC format |
| 15 | No permission to change parameter |
| 26 | Password not unique |
| 28 | Duplicate MAC address |

=== Успешный ответ ===

<code json>
{
    "result": "ok",
    "uid": 12345
}
</code>

=== Пример запроса ===

<code>
https://admin.mikbill.pro/json/index/usermanager?key=MY_API_KEY&request=update_user&uid=12345&fio=Петров Пётр&phone=0509876543&gid=7
</code>

----

===== Примеры использования =====

==== cURL ====

<code bash>
# Получить информацию об API
curl "https://admin.mikbill.pro/json/index/usermanager?key=MY_API_KEY&request=get_api_information"
</code>
<code bash>
# Создать абонента
curl -X POST "https://admin.mikbill.pro/json/index/usermanager" \
  -d "key=MY_API_KEY" \
  -d "request=create_user" \
  -d "connectiontemplateid=1" \
  -d "user=newuser" \
  -d "password=SecurePass123" \
  -d "gid=5" \
  -d "fio=Иванов Иван" \
  -d "phone=0501234567" \
  -d "houseid=42" \
  -d "app=101"
</code>
<code bash>
# Получить данные абонента
curl "https://admin.mikbill.pro/json/index/usermanager?key=MY_API_KEY&request=get_user_data&uid=12345"
</code>
<code bash>
# Обновить данные абонента
curl -X POST "https://admin.mikbill.pro/json/index/usermanager" \
  -d "key=MY_API_KEY" \
  -d "request=update_user" \
  -d "uid=12345" \
  -d "gid=7" \
  -d "phone=0509876543"
</code>

==== PHP ====

<code php>
$params = [
    'key'     => 'MY_API_KEY',
    'request' => 'get_user_data',
    'uid'     => 12345,
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://admin.mikbill.pro/json/index/usermanager');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
</code>