Биллинг-интеграция

GetOLT не заменяет биллинг и не хранит данные абонентов локально. Вместо этого продукт подключается к БД биллинга оператора (или к его API) и подтягивает данные на лету: договор, ФИО, адрес, тариф — по MAC-адресу зарегистрированной ONU.

Это даёт техподдержке полную картину «кто стоит за этой ONU» без переключения окна, а инженерам — возможность фильтровать ONU по биллинговым атрибутам (тариф, дата подключения, статус договора).

Архитектура интеграции

[ Биллинг оператора ] ── JDBC / API ──> [ GetOLT ] ── веб-интерфейс / REST API
        ↑                                    │
        │                                    └── локальный кэш (Caffeine, TTL настраивается)
        │
    оператор, поддержка

GetOLT обращается к биллингу read-only: ничего не пишет, не изменяет договоры, не обновляет статусы. Все операции на стороне биллинга остаются у его штатной системы.

Подключение

Каждый биллинг устроен по-своему — схема таблиц, имена колонок, способы хранения MAC-адреса (нижний/верхний регистр, разделители : / -, без разделителей) различаются. Поэтому интеграция настраивается под конкретный биллинг оператора при внедрении.

Минимальный набор параметров для JDBC-подключения через переменные окружения:

# Включить интеграцию с биллингом
BILLING_ENABLED=true

# JDBC-параметры подключения к БД биллинга
BILLING_DB_URL=jdbc:postgresql://billing.company.local:5432/billing
BILLING_DB_USERNAME=getolt_reader
BILLING_DB_PASSWORD=<пароль read-only пользователя>
BILLING_DB_DRIVER=org.postgresql.Driver

# Запрос, который маппит MAC ONU на договор/абонента
BILLING_QUERY_BY_MAC=SELECT contract_id, customer_name, address, tariff FROM v_subscribers WHERE LOWER(mac) = LOWER(:mac)

# Время жизни записи в кэше GetOLT (минуты)
BILLING_CACHE_TTL_MINUTES=60

Поддерживаются MySQL/MariaDB, PostgreSQL, MSSQL — любой биллинг с JDBC-драйвером. Если у вас биллинг с REST API (без прямого доступа к БД) — интеграция собирается под него отдельно, напишите в support@getolt.online.

Что нужно подготовить на стороне биллинга

1. Read-only пользователь для GetOLT — без прав на запись и без доступа к платёжной информации (если в биллинге это разделено).
2. View или подготовленный запрос — лучше не давать GetOLT доступ к сырым таблицам биллинга, а собрать представление v_subscribers с нужными колонками. Это позволяет менять схему биллинга, не трогая GetOLT.
3. Сетевая связность от хоста GetOLT до сервера биллинга (обычно 5432/tcp для PostgreSQL или 3306/tcp для MySQL).

Маппинг колонок

В запросе BILLING_QUERY_BY_MAC колонки результата должны называться:

Колонка результата	Что это	Обязательность
contract_id	Номер договора абонента	обязательно
customer_name	ФИО или название юр.лица	обязательно
address	Адрес подключения	обязательно
tariff	Название тарифа	опционально
status	Статус договора (активен/заблокирован)	опционально

Если в биллинге другие имена — переименуйте в запросе через AS: SELECT contract_no AS contract_id, ....

MAC-адрес — нюанс форматов

Один из самых частых источников «биллинг не находит абонента» — несовпадение формата MAC. Биллинги хранят MAC по-разному:

• 00:11:22:33:44:55 — нижний регистр, двоеточия
• 00-11-22-33-44-55 — дефисы
• 001122334455 — без разделителей
• 00:11:22:33:44:55 против 0:11:22:33:44:55 — с/без ведущих нулей

В запросе всегда нормализуйте к одному формату: LOWER(REPLACE(mac, ':', '')) или аналогично в синтаксисе вашей СУБД. GetOLT отдаёт MAC в нижнем регистре с двоеточиями — этот формат и подставляется в плейсхолдер :mac.

Кэширование

Прямой запрос в биллинг на каждый просмотр абонента — лишняя нагрузка. GetOLT кэширует результат на стороне приложения через Caffeine. TTL задаётся BILLING_CACHE_TTL_MINUTES (по умолчанию 60 минут — компромисс между свежестью данных и нагрузкой на биллинг).

Если оператор сменил тариф, кэш в GetOLT устареет — но в пределах TTL. Для критичных сценариев (немедленная блокировка после отключения за неуплату) кэш можно сделать короче или отключить.

Проверка интеграции

После настройки переменных окружения и перезапуска контейнера:

1. Откройте любую ONU в UI GetOLT.
2. В блоке «Абонент» должны появиться contract_id, ФИО и адрес.
3. Если поле пустое — посмотрите логи GetOLT: Billing query returned 0 rows for MAC <…> обычно значит проблему с форматом MAC; Cannot connect to billing DB — сетевая или credentials.

---

Если у вас нетривиальный сценарий — два биллинга в одной сети, миграция между биллингами, биллинг с собственным API без JDBC — напишите в support@getolt.online или в Telegram @getolt_pub: такие интеграции собираются под конкретного клиента.