> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Создание компании и её адрес
> Как заводится и хранится компания: центральная запись и её вычисляемые поля, домены, транзакционный провижининг (стартовый 7-дневный период, дефолтные справочники и настройки, демо-набор интеграций по ответам онбординга), регистрация кастомного домена, справочники стран/валют/типов и единственный путь создания компании.
Полный перечень полей — в [глоссарии](/ru/logic/company-billing/setup-glossary).
## Обзор
Эта страница описывает, как в Yume заводится и хранится сама компания и её домены. Здесь собраны: центральная запись компании и её вычисляемые поля, привязанные к ней домены, создание новой компании (создание записи, стартового пробного периода, дефолтных справочников и настроек), регистрация кастомного домена, справочники стран/валют/типов компаний и два пути регистрации компании.
Компания хранится в общих таблицах базы данных и служит «якорем» всей коммерческой обвязки: к ней привязаны владелец, лимиты, домены и настройки. Все остальные модули биллинга ссылаются именно на неё.
## Модель данных
### Компания
Это основная запись компании. Она одновременно является техническим описанием компании (к ней привязаны все её данные) и коммерческой карточкой (владелец, оформление).
| Поле | Тип | Назначение |
| ----------------- | ----------- | ------------------------------------------------------- |
| Идентификатор | число | Первичный ключ компании |
| Название | текст | Название компании |
| Адрес | текст | Адрес компании |
| Начало периода | дата/время | Начало текущего оплаченного или пробного периода |
| Окончание периода | дата/время | Дата окончания подписки |
| Логотип, Фон | изображения | Оформление компании |
| Фирменный цвет | текст (HEX) | Цвет бренда, по умолчанию оранжевый (#f25a29) |
| Владелец | связь | Пользователь-владелец компании; защищён от удаления |
| Тип компании | связь | Категория/сфера деятельности; защищён от удаления |
| Страна | список | Из фиксированного перечня стран, по умолчанию Казахстан |
| Валюта | список | Из фиксированного перечня валют, по умолчанию тенге |
| Часовой пояс | текст | По умолчанию UTC |
| Доп. данные | JSON | Произвольные дополнительные данные |
| Теги | связь (M2M) | Теги компании |
| Ссылка (домен) | текст | Вычисляется автоматически (см. ниже) |
| Код типа | текст | Вычисляется автоматически из кода типа компании |
У компании нет отдельного хранилища, которое создавалось бы или удалялось вместе с её записью: данные всех компаний лежат вместе, а разделение обеспечивается на уровне самой базы. Поэтому создание компании — это создание записи, а не отдельного хранилища, и удаление записи данные других компаний не затрагивает. Подробнее — в разделе [«Разделение данных компаний»](/ru/logic/infrastructure).
#### Вычисляемые поля: Ссылка и Код типа
Список компаний при каждом запросе дополняется двумя вычисляемыми полями:
* **Ссылка (домен)** — основной (primary) домен компании в зоне `.yume.cloud`. Если такого домена нет, подставляется запасное значение `account.yume.cloud`.
* **Код типа** — машинный код типа компании, подтянутый из связанного справочника типов.
Кроме того, задаётся порядок сортировки списка компаний: сначала по дате окончания периода (сначала записи без даты, затем от более поздних к более ранним), затем по убыванию идентификатора.
Из-за запасного значения у любой компании без основного домена в зоне `.yume.cloud` «Ссылка» всегда будет равна `account.yume.cloud`. Это ожидаемое поведение, а не признак ошибки.
### Домен компании
Домен привязывается к компании и описывает, как до неё «дотянуться» из интернета.
| Поле | Тип | Назначение |
| ---------------- | ---------- | ----------------------------------------------------- |
| Домен | текст | Полное доменное имя |
| Компания | связь | Компания-владелец домена |
| Основной домен | флаг | Признак основного домена компании |
| Кастомный домен | флаг | Домен добавлен клиентом и требует внешней регистрации |
| Верифицирован | флаг | Домен подтверждён; по умолчанию — да |
| Дата верификации | дата/время | Момент успешной проверки/регистрации |
Обычные поддомены вида `<название>.yume.cloud` считаются верифицированными сразу. Признак «кастомный домен» ставится для собственных доменов клиента — их нужно дополнительно проверить и зарегистрировать во внешней системе (см. раздел о регистрации кастомного домена).
### Справочники: типы компаний, страны, валюты
**Тип компании** — это редактируемый справочник сфер деятельности (прокат авто, самокатов и т. п.). У каждого типа есть отображаемое название, машинный код, иконка, флаги «опубликован» и «активен», порядок сортировки и привязка к стране. Публичный список типов сортируется по полю порядка.
**Страна** — фиксированный перечень поддерживаемых стран: Казахстан и ОАЭ.
**Валюта** — фиксированный перечень поддерживаемых валют: тенге, доллар США, рубль, евро, узбекский сум, киргизский сом, дирхам ОАЭ, саудовский риял.
Рядом с типами компаний в системе объявлен и перечень функциональных возможностей (продукты, комплекты, услуги, инвентарь, автомобиль, автоштрафы, различные режимы аренды и инвентаризации и т. д.) — он используется при настройке того, какие функции доступны типу компании и самой компании.
### Привязка периодической задачи к компании
Отдельная сущность связывает запланированную периодическую задачу с конкретной компанией, делая фоновую задачу зависимой от компании.
| Поле | Тип | Назначение |
| ---------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| Компания | связь | Компания, к которой привязана задача |
| Периодическая задача | связь (1:1) | Задача планировщика |
| Использовать часовой пояс компании | флаг | Если включено — расписание пересчитывается в часовом поясе компании, иначе в UTC |
При сохранении привязки система:
1. Прописывает идентификатор компании в служебные заголовки задачи — благодаря этому задача при запуске выполнится в контексте нужной компании.
2. Если у задачи есть расписание по времени и включён флаг часового пояса компании — пересчитывает расписание из часового пояса компании; иначе использует UTC.
Дополнительно при сохранении самой периодической задачи система автоматически «выравнивает» её с компанией: если привязка уже есть — обновляет заголовки при расхождении, если привязки ещё нет — создаёт её на основе идентификатора компании и флага часового пояса, взятых из заголовков задачи. Компания при этом ищется через кэш; если по идентификатору компания не найдена или контекст компании не определён, выравнивание тихо пропускается.
## Как создаётся новая компания
Создание компании — это единая операция, которая заводит компанию «под ключ»: одну запись компании, стартовый период, домен, членство владельца, лимиты и полный набор дефолтных справочников и настроек. Всё это выполняется в одной транзакции — при сбое ничего не остаётся «наполовину созданным».
### Что именно создаётся
**Запись компании.** Создаётся в общих таблицах платформы. Заполняются: начало периода — текущий момент, окончание — через 7 дней, валюта (по умолчанию тенге), страна (по умолчанию Казахстан), владелец.
**Стартовый период** — пробные 7 дней от момента создания. Это и есть первичный «триал», по истечении которого требуется оплата.
**Домен** — если при создании передан поддомен, создаётся домен вида `<поддомен>.yume.cloud`. Если поддомен не передан, домен не создаётся, и «Ссылка» компании остаётся запасной (`account.yume.cloud`).
**Членство владельца** — владелец добавляется в компанию как администратор с правами суперпользователя и сотрудника.
**Лимиты плана** — создаётся начальный набор лимитов (см. ниже).
**Дефолтные справочники** (создаются как стартовое наполнение компании):
* Период времени «День» (длительность — одни сутки).
* Пункт проката «Пункт проката» с адресом-заглушкой.
* Метки клиентов: «Хороший» и «Плохой».
* Категория «Категория».
* Статусы состояния инвентаря: «Исправен» (без блокировки) и «Сломан» (с блокировкой).
* Способы привлечения клиентов: «Instagram», «Whatsapp», «Сарафанка».
* Типы оплаты: «Kaspi QR», «Kaspi RED», «Наличные».
**Настройки компании** — записи с названием, адресом, валютой и языком. Язык выбирается по стране: для ОАЭ — английский, для остальных — русский.
**Демо-доступ** — набор интеграций, который компания получает сразу при создании (см. раздел «Демо-доступ новой компании»).
**Уведомление администратора** — в конце в административный Telegram-канал отправляется уведомление «РЕГИСТРАЦИЯ КОМПАНИИ». В него вкладывается состав подключённых интеграций, поэтому на всю регистрацию уходит **одно** сообщение, а не по одному на каждый модуль.
### Стартовые лимиты плана
Генерация лимитов добавляет только те лимиты, которых у компании ещё нет (существующие не трогает), а затем сбрасывает кэш лимитов компании. Начальный набор:
| Лимит | Значение | Бесплатно | Занято |
| --------------------- | -------- | --------- | ------ |
| Персонал (сотрудники) | 2 | 2 | 1 |
| Пункты проката | 1 | 1 | 0 |
| Инвентарь: автомобили | 0 | — | — |
| Инвентарь: самокаты | 0 | — | — |
| Инвентарь: мотоциклы | 0 | — | — |
Эта же генерация вызывается повторно при открытии карточки компании, если число сохранённых лимитов не совпадает с полным перечнем типов лимитов — тогда недостающие лимиты будут дозаведены на лету.
### Демо-доступ новой компании
Сразу после создания компания получает набор подключённых интеграций — иначе в только что заведённой компании не было бы даже аренды. Набор собирается из **ответов онбординга**, которые передаются вместе с данными компании и **на самой компании не сохраняются**:
| Ответ | Что означает | Значения |
| ------ | --------------------------------- | ------------------------------------------ |
| Сфера | Чем компания занимается | «Аренда транспорта» или «Аренда инвентаря» |
| Модули | Что клиенту интересно попробовать | Список кодов интеграций, может быть пустым |
Если сфера не указана, она **выводится из типа компании**: типы «такси» и «авто» дают транспорт, все остальные — инвентарь.
Что попадает в набор:
Основной модуль аренды подключается в демо-режиме. Вариация выбирается по сфере: для транспорта — та, где в лимитах есть автомобили, для инвентаря — любая другая. К подключению сразу привязывается **самый короткий публичный тариф** этой вариации в валюте компании — это тот тариф, в который демо превратится при оплате.
Проверка должников egov подключается **без даты окончания** — она бесплатна, и демо-срок на неё тратить незачем.
Каждый модуль из ответов онбординга подключается в демо-режиме.
В наборе перечисляются только **точки входа**. Каждое подключение дальше само «разворачивается» в связанные с ним рекомендованные интеграции, поэтому конкретный состав модулей по сферам настраивается в админке, а не зашит в код провижининга.
Правила подключения одинаковы и при создании компании, и при массовом подключения из кабинета:
* Демо ставится только если у интеграции задана ненулевая длительность демо.
* Подключение, у которого **уже** есть демо-срок, оплаченный срок или тариф, **не передатируется** — то же правило, что и у ручного подключения («Демо-режим уже использован»). Если оно было отключено, его просто включают обратно.
* Неизвестные коды, повторы в списке и интеграции, которым не хватает обязательных полей настройки, **пропускаются** — один неверно настроенный модуль не роняет весь набор.
* Весь набор идёт одной транзакцией и даёт **одно** сообщение в административный канал со списком «интеграция — до какого числа — демо или нет».
### Единственный путь создания компании
Компанию создаёт **только** отдельный запрос на создание компании — от уже вошедшего пользователя, с названием, адресом, типом, валютой, страной, поддоменом и ответами онбординга. Формат валидирует поддомен, после чего запускает провижининг. Создание разрешено **только вне контекста конкретной компании**; при попытке создать компанию, когда в запросе уже определена активная компания, вернётся отказ с предложением обратиться в поддержку по указанному телефону.
Ни обычная регистрация, ни вход через Google компанию больше **не создают** — после регистрации пользователь остаётся без компании, пока сам её не заведёт. Раньше вход через Google молча провижионил компанию первому вошедшему; теперь это убрано, чтобы компания создавалась ровно в одном месте.
Пока компании нет, запросы такого пользователя к обычным разделам отклоняются с ответом **403** и кодом `tenant_required` — фронтенд по этому коду ведёт человека на создание компании. Список исключений (вход, регистрация, создание компании, справочники, заявка на демо) описан в разделе [«Как система определяет вашу компанию»](/ru/logic/user/active-company).
Компания может быть провижионена **без поддомена** — тогда доменную запись придётся завести отдельно, а до тех пор «Ссылка» компании будет запасной (`account.yume.cloud`).
## Домены и поддомены
### Проверка занятости поддомена
Перед регистрацией фронтенд проверяет, свободен ли желаемый поддомен. Правила:
* Поддомен не должен содержать пробелов.
* Если существует домен, начинающийся с введённого текста, поддомен считается занятым.
* Если поддомен входит в список зарезервированных имён, он тоже считается занятым.
Список зарезервированных (служебных) имён включает такие значения, как `docs`, `manager`, `yume`, `api`, `dev`, `widget`, `auth`, `cabinet`, `landing`, `domain`, `app`, `prod`, `stage`.
При фактическом создании компании поддомен проверяется ещё строже: сверка с зарезервированными именами и точная проверка «домен начинается с `<поддомен>.`». Если поддомен занят или зарезервирован — создание отклоняется с сообщением, что такой домен уже существует.
### Регистрация кастомного домена
Когда клиент подключает собственный домен, его нужно проверить и зарегистрировать во внешней системе. Это делает фоновая задача:
1. Берёт домен, помеченный как кастомный. Если такого нет — завершается.
2. Проверяет счётчик повторов: если он достиг предела (30 попыток) — прекращает попытки.
3. Разрешает домен в IP-адрес. Если DNS ещё не отвечает — планирует повтор через 15 минут. Если IP не совпадает с ожидаемым адресом платформы — завершается с сообщением о несовпадении.
4. Если IP совпал — обращается к внешнему сервису регистрации (с ключом доступа). При успешном ответе помечает домен верифицированным и проставляет дату верификации. При неуспехе или ошибке связи — планирует повтор через 15 минут.
Логика повторов рассчитана примерно на 30 попыток с интервалом 15 минут, то есть верификация кастомного домена может «дозревать» в течение нескольких часов, пока DNS-записи клиента распространяются.
## Как это используется
### API компаний и справочников
* **Список компаний / создание компании** — возвращает компании, где текущий пользователь является администратором-сотрудником; создание доступно только вне контекста конкретной компании. Это единственная точка, создающая компанию, и она же принимает ответы онбординга (сфера, модули), формирующие демо-набор.
* **Карточка компании** — чтение и обновление данных текущей компании; при открытии дозаводит недостающие лимиты. Если компания в запросе не определена, возвращается **404** с сообщением «Пользователь не подключён к компании» — тот же ответ, что и для несуществующей компании, вместо ошибки на пустом объекте.
* **Массовое подключение интеграций** — подключает сразу список модулей (`POST /v1/crm/integrations/bulk_connect/`), по тем же правилам, что и демо-набор при регистрации: пропуск неизвестного и ненастраиваемого, одна транзакция, одно сообщение администраторам. В ответе — список того, что действительно подключилось.
* **Список типов компаний** — публичный справочник, отсортированный по порядку.
* **Шаги онбординга** — список и отметка пройденных шагов для текущей компании.
* **Заявка на демо** — принимает телефон, ФИО и сферу деятельности и отправляет уведомление в административный Telegram-канал.
* **Проверка поддомена** — см. выше.
### Инвалидация кэша компании
Компании кэшируются (по идентификатору и по именам доменов). При **обновлении** записи компании кэш сбрасывается автоматически: удаляется запись по идентификатору и записи по всем доменам этой компании. При **создании** компании сброс кэша не выполняется (кэшировать ещё нечего).
### Устаревший вход компании
Есть отдельная точка входа компании, возвращающая данные сессии, но с пустым идентификатором компании в ответе. Она помечена как устаревшая и подлежит удалению после обновления мобильных приложений — новый код на неё завязывать не следует.
## Связанные страницы
Полный перечень полей компании, домена, справочников и привязки периодических задач.
Обзорная страница модуля: как связаны компании, подписки, счета и платежи.
Сводный список известных багов и логических нюансов всего модуля биллинга.
Счета, их позиции и ошибки, расчёт суммы, инициация оплаты и обработка ответа от платёжной системы.
Сохранённые платёжные карты компании и их привязка к автоматическим списаниям.
Интеграция с платёжным шлюзом (подпись, инициация платежа/карты, списание и возврат) и legacy-клиент.
Лимиты плана по ресурсам (сотрудники, точки, транспорт), их цены по периодам и пересчёт потребления.
Шаги онбординга компании, лента новостей, снапшоты системной статистики и фоновые задачи.