Задача
Агентская сеть означает, что в одной системе работают компании, которые не должны видеть друг друга вообще. Ни остатков, ни клиентов, ни истории платежей, ни справочников.
При этом каждая из них хочет подключиться к платформе программно, а не сидеть в кабинете руками. Значит, нужен публичный API, документация к нему и предсказуемое поведение, по которому партнёр судит о платформе ещё до подписания договора.
Решение
Платформа разделена на четыре части с раздельными задачами: приватный API для кабинета, публичный JSON-RPC для интеграторов, сам кабинет агента и отдельный сайт документации.
Изоляция арендаторов проходит через все слои. Каждая выборка ограничена арендатором, и это не соглашение между разработчиками, а требование, которое проверяется отдельно, потому что одна забытая проверка означает чужие данные на экране.
Деньги считаются двухфазно. Платёж резервируется, уходит провайдеру, и только подтверждение провайдера превращает резерв в проводку. Комиссия агента и его вознаграждение считаются по настройкам конкретной пары «арендатор и услуга», а не общей формулой.
Архитектура и реализация
Что вошло:
· приватный API кабинета и публичный JSON-RPC для внешних интеграторов
· кабинет агента: баланс, платежи, история, отчёты
· каталог услуг с полями, зависящими от провайдера, включая каскадные списки
· двухфазный платёж со статусами и разбором зависших операций
· настройки комиссии и вознаграждения по каждой услуге арендатора
· двухфакторная аутентификация
· публичный сайт документации API
Стек: NestJS, PostgreSQL с функциями и триггерами, Redis с очередями, React в кабинете.
Результат
Платформа работает на проде и обслуживает агентов, а её публичная документация выполняет отдельную работу. Именно по ней внешние платёжные компании оценивают, стоит ли с нами интегрироваться, и приходят с предложениями подключить свои страны.
Это редкий случай, когда качество API напрямую приводит партнёров.
