> ## 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.
# Инвойсы и платежи
> Счета на оплату подписки и модулей: статусы платежа и типы позиций, расчёт суммы, оплата через FreedomPay, вебхук результата, провижининг лимитов/SMS/интеграций и выдача пакета документов при подтверждении, а также рекуррентное автопродление по сохранённой карте.
Полный перечень полей — в [глоссарии](/ru/logic/company-billing/invoices-glossary).
Эта страница описывает, как в Yume устроены счета на оплату подписки и модулей, как проходит платёж через шлюз FreedomPay, что происходит после подтверждения оплаты и как работает автоматическое (рекуррентное) продление по сохранённой карте.
## Что такое инвойс
**Инвойс (счёт на оплату)** — это счёт компании на оплату подписки, модулей, интеграций или дополнительных лимитов. Каждый счёт принадлежит одной компании, оплачивается через платёжный шлюз (сейчас поддерживается только FreedomPay) и состоит из одной или нескольких **позиций**.
Счёт хранит две группы сумм и дат:
| Поле | Тип | Назначение |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| Сумма к оплате | число (2 знака) | Итоговая сумма счёта, рассчитанная из позиций |
| Списанная сумма | число (2 знака) | Фактически захваченная сумма после подтверждения оплаты |
| Сумма возврата | число (2 знака) | Возвращённая сумма (при возврате платежа) |
| Валюта | текст | По умолчанию тенге (KZT) |
| ID транзакции | текст | Идентификатор платежа во FreedomPay |
| Ссылка на оплату | текст | URL страницы оплаты, куда перенаправляется плательщик |
| Данные платежа | структура (JSON) | Телефон, маскированный номер карты, срок, владелец, бренд и способ оплаты — заполняется из вебхука |
| Дата списания | дата/время | Момент подтверждения оплаты |
| Начало / Конец периода | дата/время | Границы оплаченного периода подписки |
К счёту также привязана **Платёжная карта** — сохранённая карта компании, если она есть. Если карту позже удалят, ссылка на неё в счёте обнуляется, но сам счёт сохраняется.
В карточке счёта соседствуют **две разные карты**, и их не следует путать:
* **привязанная к счёту** — та сохранённая карта компании, под которую счёт выставлялся (может быть уже удалена);
* **карта из данных платежа** — та, которой эквайринг фактически провёл оплату.
Обычно это одна и та же карта, но совпадать они не обязаны, поэтому в истории показываются обе.
Сведения о **способе оплаты** доступны по счёту, который был оплачен, — то есть и по подтверждённому, и по **возвращённому**: возвращённый счёт когда-то был оплачен, и история обязана показывать, чем именно. По отклонённому счёту таких сведений нет вовсе — данные карты пишутся только на успешном ответе шлюза.
### Статус платежа
Каждый счёт проходит по одному из четырёх состояний:
| Статус | Что означает |
| ----------- | ------------------------------------------------------------- |
| В ожидании | Счёт создан, оплата ещё не завершена (состояние по умолчанию) |
| Подтверждён | Оплата прошла — запускается провижининг (см. ниже) |
| Отклонён | Оплата не удалась, создаётся запись об ошибке |
| Возвращён | Средства возвращены плательщику |
Переход в статус «Подтверждён» — ключевое событие всего биллинга. Именно он включает купленные лимиты, интеграции и пополняет баланс SMS.
### Позиции счёта
Каждая **позиция инвойса** описывает одну оплачиваемую вещь. Тип позиции определяет, что именно покупается:
| Тип позиции | Что оплачивается |
| --------------------------------- | -------------------------------- |
| Пользовательские места | Количество сотрудников/аккаунтов |
| Точки аренды | Количество точек проката |
| Автомобили / Самокаты / Мотоциклы | Объём инвентаря по видам техники |
| Модуль | Функциональный модуль системы |
| Интеграция | Подключение внешней интеграции |
По смыслу позиции делятся на две группы:
* **Лимитные** позиции (места, точки, три вида инвентаря) — увеличивают лимиты плана компании.
* **Модули и интеграции** — подключают функциональность или внешний сервис на срок.
Позиция хранит количество единиц, цену, сумму (дублирует цену), а также границы своего периода. Для модулей и интеграций к позиции привязан **тарифный период интеграции** — выбранный тариф с ценой и длительностью.
В рамках одного счёта не может быть двух позиций с одинаковой парой «тип + тарифный период интеграции» — это защищено ограничением уникальности на уровне базы.
#### Что позиция показывает в истории
Чтобы историю счетов можно было читать без расшифровки, позиция отдаёт вместе с собой:
| Что | Зачем |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Готовая подпись | Тот же человекочитаемый текст, что и в детализации перед оплатой: «СМС Центр (200 шт.)», «Автомобили». История и корзина называют вещи одинаково. |
| Оплаченный тариф целиком | Вид тарифа (периодный или количественный), срок и **прейскурантная** цена — по ним видно «12 мес.» или «пакет 200 шт.» и цена без скидки. |
| Интеграция и вариация | Что именно оплачено (у лимитных позиций пусто — они тарифицируются поштучно, а не по тарифу). |
### Ошибки оплаты
Если платёж отклонён, к счёту привязывается **Ошибка оплаты инвойса** — запись с кодом и текстовым описанием причины, полученными от FreedomPay. У одного счёта может накопиться несколько таких записей (например, при нескольких неудачных попытках).
## Расчёт суммы счёта
Прежде чем создать счёт, система рассчитывает цену каждой позиции и итог. Расчёт выполняет **единое ядро**, общее для оплаты из кабинета, автопродления и регистрации оплаты в админке, — поэтому предварительная оценка, сумма счёта и сумма списания всегда совпадают.
Коротко о правилах:
* **Модули и интеграции** тарифицируются по выбранному тарифу. Новый срок пристыковывается к концу уже оплаченного (но не раньше «сейчас»), поэтому досрочное продление не сжигает остаток. Количественные тарифы (пакеты единиц вроде SMS) стоят фиксированную цену и **не имеют даты окончания**.
* **Лимитные позиции** тарифицируются по циклу компании — длительности тарифа её подписки «аренда» (1, 3, 6 или 12 месяцев; месяц, если тарифа нет). Платят только за превышение бесплатного объёма и только за прирост к уже оплаченному количеству. Увеличение в середине действующего срока доплачивается **пропорционально остатку** срока; уменьшение применяется сразу, бесплатно и без возврата.
* **Режим «продлить всё до даты»** тарифицирует всю корзину пропорционально дням до указанной даты, автоматически подбирая месячный, трёхмесячный, полугодовой или годовой прайс по фактическому сроку.
* Цена каждой позиции округляется до десятков тенге, итог счёта — сумма цен всех позиций.
Предварительная оценка возвращает не только итог, но и **построчную детализацию**: оплачиваемые единицы, цену за период, число оплачиваемых дней, сумму и дату окончания по каждой позиции, включая бесплатные связанные интеграции.
Полное описание правил расчёта, обоих режимов тарификации, автоподбора прайса и защиты от подорожания — на странице [«Расчёт стоимости и регистрация оплаты»](/ru/logic/company-billing/pricing).
Прайс лимитов поддерживает только фиксированный набор длительностей периода (1, 3, 6 и 12 месяцев). Если для ресурса не настроена цена нужного периода, расчёт использует месячную цену, а при её отсутствии завершается ошибкой — но только если в корзине действительно есть платные единицы этого ресурса.
## Создание и оплата счёта
### Список и создание счетов
Список счетов компании показывает все **подтверждённые, отклонённые и возвращённые** счета, плюс любые **свежие счета за последние 3 дня** (независимо от статуса). Более старые счета «в ожидании» в списке не показываются.
При создании счёта:
1. Рассчитываются позиции и итоговая сумма.
2. Формируется список позиций фискального чека для передачи в шлюз.
3. К счёту привязывается активная карта компании, если она есть.
4. Если итог меньше 1 тенге — создание отклоняется с ошибкой «Сумма счёта не может быть 0 тенге».
5. Создаётся счёт, инициируется платёж во FreedomPay, сохраняются идентификатор транзакции и ссылка на оплату.
6. Создаются позиции счёта.
7. Администраторам уходит уведомление «Попытка оплаты».
Хотя к счёту может быть привязана карта, автоматическое прямое списание при создании счёта через API сейчас отключено внутренним флагом. На практике клиент всегда получает ссылку на оплату и проходит платёж на странице FreedomPay. Автосписание с карты работает только в фоновой задаче рекуррентного продления (см. ниже).
### Деталь, обновление и удаление счёта
По конкретному счёту можно получить детали, удалить его, а также запросить обновление — при обновлении система дополнительно опрашивает FreedomPay о текущем статусе платежа (синхронизация).
### Повторная (ручная) оплата
Если счёт остался неоплаченным, можно повторно инициировать оплату — система заново формирует ссылку на оплату по существующему счёту без автосписания с карты.
Повторную оплату нельзя запустить для счёта в статусе «Подтверждён» или «Возвращён» — попытка вернёт ошибку.
### Оплата мимо шлюза (регистрация вручную)
Если компания заплатила банковским переводом или наличными, сотрудник Yume регистрирует такую оплату из админки. Счёт при этом создаётся **сразу подтверждённым**: списанная сумма равна итогу, а в данных платежа сохраняется отметка о ручной регистрации, автор и комментарий. Никакого обращения к шлюзу не происходит, но провижининг срабатывает штатно — так же, как после оплаты картой.
Ручные оплаты отличимы от эквайринговых везде, где показывается способ оплаты: в карточке счёта, в истории счетов клиента, в уведомлении администраторам и в счётчике «вручную» на дашборде.
Сценарий работы оператора описан на странице [«Расчёт стоимости и регистрация оплаты»](/ru/logic/company-billing/pricing).
## Вебхуки платежа: проверка и результат
FreedomPay обращается к двум публичным адресам (без авторизации системы): **проверка платежа** — можно ли оплатить этот заказ, и **результат платежа** — чем всё закончилось. Оба обслуживает один обработчик, который различает их по адресу вызова.
### Проверка подписи
Прежде чем что-либо менять, обработчик **проверяет подпись входящего запроса** по секрету мерчанта. Запрос с неверной подписью отклоняется, никакие статусы не меняются. Ответ шлюзу тоже подписывается.
Тонкость шлюза: подпись строится с «именем операции» в начале, и для адреса, заканчивающегося слешем, FreedomPay использует **пустое имя** вместо последнего сегмента пути. Поэтому обработчик перебирает возможные варианты имени, а найденным подписывает свой ответ. Без этого все легитимные колбэки отклонялись бы.
### Предварительная проверка платежа
На запрос проверки система отвечает, можно ли оплатить заказ:
| Ситуация | Ответ шлюзу |
| ----------------------------------------- | --------------------------- |
| Счёт не найден | Отказ — «заказ не найден» |
| Сумма платежа не совпадает с суммой счёта | Отказ — «расхождение суммы» |
| Счёт уже оплачен | Отказ — «заказ уже оплачен» |
| Всё в порядке | Разрешение оплаты |
### Результат платежа
| Код результата | Действие |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 (успех) | Статус счёта → «Подтверждён»; сохраняются данные карты и телефон, дата и сумма списания; администраторам уходит уведомление «Оплата инвойса» со способом оплаты |
| 0 (отказ) | Статус → «Отклонён»; создаётся запись об ошибке с кодом и описанием причины |
| 2 (не завершён) | Статус не меняется; возвращается подтверждающий XML |
Дата списания берётся из данных платежа (если пришла) и приводится к часовому поясу системы; если её нет — подставляется текущий момент.
### Повторные и запоздавшие колбэки
Обработчик **идемпотентен** по уже оплаченному счёту:
* повторный успешный колбэк по подтверждённому счёту получает ответ «уже оплачен» и ничего не переписывает — провижининг не выполняется второй раз;
* колбэк об отказе **не может** перевести подтверждённый счёт в «Отклонён» (запоздавший отказ не отменяет успешную оплату).
При внутренней ошибке обработки обработчик отвечает кодом 500 (раньше отвечал 200). Это намеренно: шлюз повторит доставку, и оплата не потеряется. Обратная сторона — текст ошибки попадает в ответ шлюзу.
## Что происходит при подтверждении оплаты
Как только счёт переходит в статус «Подтверждён», автоматически (при сохранении счёта) срабатывают два независимых обработчика. Оба ничего не делают, если статус не «Подтверждён».
### Провижининг лимитов, SMS и интеграций
Первый обработчик проходит по всем позициям счёта:
* **Лимитная позиция** — создаёт или обновляет соответствующий лимит плана компании: объём лимита ставится равным количеству из позиции, а границы лимита — периоду позиции.
* **Позиция интеграции SMS** — пополняет баланс SMS компании. Баланс хранится в деньгах, поэтому количество сообщений в пакете умножается на **цену одного SMS для этой компании** (поле «Цена SMS» на её SMS-аккаунте, по умолчанию 27 ₸). По той же цене сообщения потом и списываются, так что количество сообщений в пакете от цены не зависит.
* **Любая позиция интеграции/модуля** — подключает интеграцию. Берётся существующее подключение компании (приоритет у боевого, при его отсутствии — демо-подключение) и переводится в оплаченное: новый тариф, отметка «подключено», новые даты, **признак демо снимается**. Если подключения нет — создаётся новое. Для количественных тарифов дата окончания не ставится вовсе: такой пакет не истекает по времени.
Оплата **конвертирует пробное подключение в боевое в той же записи**, а не создаёт вторую рядом. Это важно: две записи по одной интеграции (пробная и оплаченная) приводили к тому, что пробная могла «перекрыть» оплаченную при проверке доступа.
Провижининг выполняется каждый раз при сохранении счёта в статусе «Подтверждён». Для лимитов и интеграций это безопасно (создание-или-обновление перезаписывает те же записи), и пополнение баланса SMS тоже идёт через создание-или-обновление по паре «компания + позиция», поэтому повторное сохранение того же счёта не задваивает баланс.
### Выдача пакета документов
Второй обработчик при подтверждении оплаты выдаёт **пакет подписей документов** для оплаченных позиций тарифа модуля электронной подписи. Уже выданные пакеты пропускаются (повторно не создаются и не суммируются).
Расходуется купленный пакет или нет — зависит от режима биллинга подписания, который платформа назначает компании. В режиме «за SMS» (он по умолчанию) компания платит только за сообщения подписания, и слоты пакета не списываются; в режиме «за документ» каждый подписываемый документ стоит один слот, а при нулевом остатке подписание по ссылке блокируется. Пакет выдаётся одинаково в обоих режимах.
Подробнее о жизненном цикле пакетов, балансе документов и квотах: [«Пакеты подписей документов»](/ru/logic/documents/packages).
## Рекуррентное (автоматическое) продление
Фоновая периодическая задача продлевает подписки по сохранённым картам с включённым автосписанием.
Как она работает:
1. Отбираются активные карты с включённым автосписанием, у которых есть подключённая интеграция, **истекающая в течение ближайших суток**.
2. Для каждой такой карты собираются действующие сейчас модули и интеграции компании (из ранее подтверждённых счетов).
3. По ним рассчитываются новые цены и периоды (та же логика расчёта — с пристыковкой к концу текущего периода).
4. Создаётся новый счёт, привязанный к карте.
5. Платёж инициируется и **сразу списывается напрямую** по сохранённому токену карты — без участия пользователя.
6. Создаются позиции нового счёта.
Дальше исход списания приходит обычным вебхуком, и при подтверждении срабатывает тот же провижининг, что и при ручной оплате.
Рекуррентное продление продлевает только модули и интеграции — лимитные позиции (места, точки, инвентарь) в автосписание не попадают.
## Связанные страницы
Полный перечень полей счёта, позиций, статусов и данных платежа.
Единое ядро расчёта, два режима тарификации, детализация и регистрация офлайн-оплаты.
Обзорная страница всего модуля компаний, подписок и платежей.
Модель компании и её домены, генерация новой компании и регистрация владельца.
Сохранённые платёжные карты компании и их привязка к автоматическим списаниям.
Интеграция с FreedomPay: подпись, инициация платежа, списание, возврат.
Лимиты плана по ресурсам, их цены по периодам и пересчёт фактического потребления.
Шаги онбординга компании, лента новостей и снапшоты системной статистики.