Документация

API

Формат запросов, ответов и справочник полей для интеграций.

Формат Организации Персонал Ресурсы Группы услуг Услуги Клиенты События Записи Кастомные поля Финансы

Финансовый API кабинета

Финансовый API работает в текущей организации с правами авторизованного пользователя — через сессию кабинета или его API-ключ. Модуль должен быть включён. Для записи нужны подходящий действующий тариф и права владельца, администратора или разрешение сотруднику. Владелец и администратор сохраняют чтение истории ранее включённого модуля после окончания тарифа; запись в этом режиме запрещена. Проверяйте context.access.can_read, can_write и history_only. API-ключ не расширяет права пользователя и не обходит ограничения модуля или тарифа.

Адрес: /api/?mod=finance&action=.... Чтение использует GET и параметры строки запроса; изменения — POST с JSON-телом и Content-Type: application/json. Для серверной интеграции передавайте Authorization: Bearer <api_key> или запасной заголовок X-API-Key: <api_key>. Ключ определяет пользователя и организацию так же, как в остальных разделах API. У финансов отдельный контракт данных: общий CRUD через mod=data/save_data/delete_data здесь не применяется.

Ключ только для чтения позволяет выполнять доступные пользователю GET-запросы, включая историю, отчёты и выгрузку export. Все POST-действия запрещены с кодом 31, в том числе sync_regular: синхронизация создаёт регулярные ожидания. Ключ с правом записи допускает POST только при context.access.can_write=true. Код 1367 также означает запрет изменения ключом «только чтение»; недоступный тариф даёт 1364, а отсутствие разрешения или выключенный модуль — 1365.

Начните с action=context: ответ содержит access, timezone, today, now, categories, methods, currencies. Берите ID категории и способа оплаты из этих справочников, а клиента и посещение — из clients и bookings. Проверяйте направление и вид категории: денежная cash, возврат refund, списание долга writeoff.

Деньги передаются десятичными строками, например "1250.50"; ответы сохраняют два знака после точки. На входе разрешены до 16 цифр до точки и до двух после неё, без знака, пробелов и запятой. Фактическая оплата положительна; сумму отдельного обязательства при изменении и цену посещения можно явно уменьшить до "0.00" с учётом уже закрытой суммы. Валюты — RUB, USD, EUR; они не складываются и не конвертируются друг в друга.

В финансовых запросах и результатах пользовательские даты и время относятся к context.timezone организации. Используйте YYYY-MM-DD HH:mm:ss либо календарную дату YYYY-MM-DD. Финансовые ответы не добавляют автоматически пары _iso_string/_timezone из общего CRUD-контракта. Для фактического действия будущая дата запрещена; будущий срок задаётся у ожидания. Отдельное правило UTC действует только для UNTIL с Z в расписании.

Общие параметры, фильтры и повторы

Поля обязательны только для методов, где они перечислены ниже. Организация определяется текущей сессией или API-ключом; попытка подменить её даёт 1382. Булевы GET-параметры принимают true/false или 1/0; в JSON используйте boolean. Все изменения выполняются атомарно: ошибка откатывает данные, историю, финансовые события и ключ запроса.

Параметр	Формат	Назначение и ограничения
`request_id`	`string, 8–100`	Обязателен у всех POST-действий, кроме `sync_regular`. Допустимы латинские буквы, цифры, дефис и подчёркивание. Повтор успешного action с прежним телом возвращает сохранённый результат с `replayed=true`; другое тело с тем же ключом даёт `1383`. Для нового действия создавайте новый ключ.
`id / version`	`integer`	При создании ID не передают. Для изменения, отмены или пропуска передайте ID нужной сущности и её актуальную версию из последнего чтения. При `1385` перечитайте данные; увеличение номера на клиенте не решает конфликт.
`client_id / booking_id`	`integer`	Необязательные связи, отсутствие связи — `0`. ID относится к сущности выбранной организации. При оплате посещения клиент должен совпадать с клиентом посещения; распределение по разным клиентам запрещено.
`category_id / method_id`	`integer`	Для нового движения выбирайте действующие записи из `context`. Способ обязателен для каждой денежной строки. Архивную запись нельзя выбрать заново, но неизменённая прежняя ссылка сохраняется при допустимом редактировании.
`amount / currency`	`string / RUB \| USD \| EUR`	Строка суммы и отдельный код валюты обязательны в денежных методах. Все строки и распределения одного действия используют одну валюту.
`occurred_at / due_at`	`YYYY-MM-DD HH:mm:ss`	Время фактического действия и срок обязательства. Если время действия не передано, используется текущее. Дата без времени означает локальную полночь; для конца фильтра `to` — `23:59:59`.
`from / to / as_of`	`YYYY-MM-DD \| YYYY-MM-DD HH:mm:ss`	Границы `from/to` включительны. Журнал фильтрует операции по `occurred_at`, ожидания — по `due_at`. `as_of` используется в балансах, отчётах и расчётах допустимой оплаты; у обычного списка это не общий фильтр состояния.
`page / page_size`	`integer`	Для клиентов, посещений, операций и обязательств: страница от 1, по умолчанию `page=1`, `page_size=30`, максимум 100. `total` относится ко всем отобранным строкам, а не только текущей странице.
`direction / state / currency`	`string`	Направление — `income` или `expense`. `state` относится к запрашиваемой сущности: у операций и обязательств разные состояния. Срезы и сводки считаются отдельно по валютам.
`client_id / booking_id / category_id / method_id / author_id`	`integer`	Журнал поддерживает перечисленные ID. У обязательств нет фильтра способа оплаты или автора. В объединённом журнале выбор `method_id` или `author_id` оставляет только фактические операции. Фильтр посещения учитывает связанные распределения, а не только прямую ссылку операции.
`clients_only`	`boolean`	Показывает строки с клиентом, исключая движения без клиента; применяется к журналу и обязательствам.
`include_expected / journal_view`	`boolean / all \| actual \| expected \| debt`	`include_expected=true` объединяет операции и обязательства. `journal_view`: все строки, фактические, неподтверждённые ожидания или подтверждённые долги. Проверяйте `row_type`: одинаковые числовые ID разных типов не означают одну сущность.
`outstanding_only / show_deleted`	`boolean`	`outstanding_only=true` у обязательств оставляет открытые положительные остатки. `show_deleted=false` у операций, журнала и сводки посещения скрывает отменённые операции; без параметра история сохраняется. `deleted_count` возвращает их количество независимо от видимости.

Полный реестр чтения: GET

Каждая строка — отдельный action модуля finance. Ответы ниже описывают содержимое data. Обычные чтения не создают регулярные платежи: при необходимости выполните отдельный sync_regular с правом записи. Ключ только чтения получает уже созданные ожидания.

action	Параметры	Результат и особенности
`context`	`—`	Доступ и финансовые справочники: `access, timezone, today, now, categories, methods, currencies`. `access` содержит доступность чтения/записи и причину ограничения.
`categories`	`—`	`items` эффективных системных и собственных категорий: ID, версия, код, имя, направление, вид, признаки `is_system/archived`.
`methods`	`—`	`items` способов оплаты с ID, версией, кодом, именем и признаками `is_system/archived`.
`clients`	`q, id, page, page_size`	Поиск по имени и необязательный точный ID. Возвращает `items, total, page, page_size`; у клиента — `id/name`.
`bookings`	`q, id, client_id, page, page_size`	Поиск по названию, ID или клиенту. `items, total, page, page_size`; строки содержат клиента, сроки, признаки завершения/отмены, `price_totals` и `price_version`.
`operations`	`from, to, client_id, booking_id, category_id, method_id, author_id, direction, currency, state, clients_only, include_expected, journal_view, show_deleted, page, page_size`	`items, totals, total, deleted_count, page, page_size`. Поддерживает обычный и объединённый журнал. Для подбора источника возврата есть отдельный режим `for_refund`, описанный ниже.
`obligations`	`from, to, client_id, booking_id, category_id, direction, currency, state, clients_only, outstanding_only, for_payment, page, page_size`	`items, totals, total, page, page_size`. Строка содержит сумму, оплату, списание, остаток, срок и связи. Сводка `totals` заполняется при `outstanding_only=true`; `for_payment` добавляет допустимый `allocation_limit`.
`client_balance`	`client_id, as_of; for_payment, currency, correction_id, version`	`totals` по валютам: свободный аванс, резерв, долг, просрочено. Без ID клиента — общая сводка клиентов организации. В режиме `for_payment=true` обязательны клиент и валюта; добавляется `available_to_allocate`.
`booking_summary`	`booking_id, show_deleted; for_payment, as_of, correction_id, version, currency, for_writeoff`	Обязателен `booking_id`. Возвращает `booking, totals, operations, deleted_count, price_totals` и актуальную `price_version`, когда доступна. Режим оплаты добавляет лимит распределения; история источников не становится повторным приходом посещения.
`booking_summaries`	`booking_ids`	Обязательная строка из 1–100 ID посещений через запятую. `items` содержит `booking_id, totals, confirmed, has_finance, price_totals, price_version, finance_price_totals` доступных посещений.
`operation_history`	`id`	Обязателен ID операции. `items` истории создания, редактирования, замены, отмены и согласования: `action, author_id, author_name, occurred_at, before, after, replacements, reason`.
`cancellation_preview`	`id`	Обязателен ID операции. Возвращает `operations, releases, price_effects, price_changes, fingerprint` перед каскадной отменой. Сам просмотр ничего не отменяет.
`recurring`	`—`	`items` настроек расписаний с версиями, условиями и `next_payment_on`. Это ближайший открытый непогашенный платёж либо прогноз до материализации; при паузе или исчерпанном правиле — `null`.
`recurring_history`	`id`	Обязателен ID расписания. `items` с `entity=recurring`, действиями `created/edited`, автором, датой, `before/after/reason`. Неизменённые условия не создают лишних пунктов истории.
`reports`	`from, to, as_of, client_id, booking_id, category_id, method_id, author_id, direction, currency`	`summary, daily, by_category, by_method, by_client, by_author, by_service, by_staff`. По умолчанию `to` — сегодня, `as_of` — конец периода. Денежные фильтры категории/способа/автора/направления/валюты относятся к денежной части, а не ко всем историческим остаткам.
`export`	`scope=operations \| reports`	Обязателен `scope`. При `operations` применяются параметры журнала, при `reports` — отчётов. Возвращает JSON с `filename, mime, content`, а не бинарный файл и не ссылку скачивания.

Полный реестр изменений: POST

Во всех строках, кроме sync_regular, дополнительно обязателен request_id. В таблице перечислены основные поля; условия редактирования, оплаты и связей раскрыты далее. Результаты — внутри data.

action	Параметры	Результат и особенности
`save_operation`	`direction, category_id, currency, rows`	Денежный приход/расход, смешанная оплата, зачёт или списание по виду категории. Возвращает массивы `operation_ids/obligation_ids`, а не единый ID. При `mode=expected` создаёт ожидание и возвращает его `id`.
`save_obligation`	`direction, amount, currency`	Создание или изменение отдельного ожидания/долга; при изменении обязательны `id/version`. Для ожидаемой оплаты посещения меняет срок по отдельному правилу ниже. Возвращает `id`.
`allocate`	`client_id, currency, allocations`	Зачёт уже полученного аванса в указанные обязательства; необязателен конкретный `source_operation_id`. Создаёт неденежную операцию `balance`, без нового денежного прихода. Возвращает массивы ID.
`initial_balance`	`client_id, type, amount, currency`	`type=advance` создаёт начальный источник `opening`; `type=debt` — подтверждённое начальное обязательство. `occurred_at/comment` необязательны. ID находятся в соответствующих массивах ответа.
`edit_operation`	`id, version, amount, currency`	Изменяет действующую операцию, сохраняя ID. Допустимы сумма/дата источника в установленных пределах либо метаданные разрешённого закрытого расчёта. Возвращает `id`; для изменения распределений используйте `correct_operation`.
`correct_operation`	`id, version; cancel \| replacement`	Отмена с `cancel=true` либо замена полным объектом `replacement`. Причина — `reason`. Каскад зависимостей требует отдельного просмотра и отпечатка. Возвращает массивы затронутых/новых ID, а для согласования — дополнительные эффекты.
`skip_obligation`	`id, version`	Помечает допустимое неоплаченное ожидание как `skipped`; `reason` необязателен. Оплата посещения, подтверждённый долг и частично оплаченный платёж не пропускаются. Возвращает массив затронутых обязательств.
`save_booking_price`	`booking_id, currency, amount`	Явно меняет общую цену посещения в одной валюте и финансовый расчёт вместе с ней. Дополнительные поля: `price_version, occurred_at, reason`. Ответ содержит массивы ID и результат изменения цены, если она изменилась.
`save_category`	`name, direction`	Создание категории; при изменении/архивировании нужны `id/version`. Дополнительно `archived`. Возвращает запись категории с актуальной версией.
`save_method`	`name`	Создание способа оплаты; при изменении/архивировании нужны `id/version`. Дополнительно `archived`. Возвращает запись способа с актуальной версией.
`save_recurring`	`name, direction, category_id, currency, amount, start_on, recurrence_rule`	Создаёт или изменяет расписание; при изменении обязательны `id/version`. Дополнительно `client_id, recurrence_start, recurrence_exdates, paused, comment`. Возвращает `id` шаблона и массивы затронутых сущностей.
`sync_regular`	`to`	Общий запуск регулярных ожиданий. `to` необязателен, `request_id` не нужен. Возвращает `complete, generated, cursor, synced_until`; при незавершённом пакете повторяйте тот же запрос с прежним `to` до `complete=true`.

Деньги, предоплата, распределения и возвраты

Фактическая операция фиксирует полученные или потраченные деньги. Обязательство фиксирует сумму, которую ещё предстоит оплатить. Зачёт использует уже полученный аванс и не увеличивает приход повторно. Категорию списания долга выбирайте из context; она требует клиента и распределения на подтверждённый долг.

Параметр	Формат	Назначение и ограничения
`mode`	`actual \| expected`	По умолчанию фактическое движение. `expected` допускает ровно одну строку `source=money` денежной категории и создаёт обязательство без денежной операции; сумму берёт из `rows[0].amount`. Будущий срок передайте как `due_at`.
`rows`	`array, 1–30`	Обязательный массив строк: каждая строка создаёт отдельную операцию. Для разделения оплаты между наличными и картой передайте две строки с разными способами.
`rows[].source`	`money \| balance`	`money` — новые деньги; `balance` — прежний аванс, только для прихода с клиентом и обязательствами. Смешанный платёж сначала использует старый аванс; излишек новых денег остаётся свободным авансом клиента.
`rows[].amount / rows[].method_id`	`string / integer`	Сумма каждой строки строго положительна. `method_id` обязателен для `money`; для зачёта аванса и списания долга денежный способ не используется.
`allocations`	`array`	Необязательное явное распределение на отдельные обязательства. Обязательства должны быть открыты и совпадать по клиенту, валюте и направлению. Одна цель не должна повторяться в массиве.
`allocations[].obligation_id / allocations[].amount`	`integer / string`	Сумма распределения положительна и не превышает доступный остаток. Частичная оплата задаёт меньшую сумму, а не новую сумму обязательства. Для расхода на обязательство и списания сумма строк должна совпадать с распределением.
`source_operation_id`	`integer`	У `allocate` выбирает конкретный источник аванса; без него используются доступные источники. У возврата обязателен и указывает исходный действующий приход `cash/opening` того же клиента и валюты.
`booking_id / client_id`	`integer`	При включённых финансах новая клиентская запись из календаря или виджета сразу получает ожидание оплаты по стоимости посещения. После отметки состоявшегося визита неоплаченный остаток становится долгом. При приходе с `booking_id` цели выбираются по финансовому расчёту посещения автоматически; `client_id` должен совпадать. Для самостоятельного обязательства используйте `allocations`. Расход может быть связан с посещением в допустимом контексте клиента.
`adjust_booking_price`	`boolean`	Возврат — `save_operation` с `direction=expense`, категорией вида `refund`, исходной оплатой и денежными строками. `booking_id` ограничивает возврат выбранным посещением. `adjust_booking_price=true` явно согласует снижение цены оказанной услуги; без этого возврат не означает автоматическое изменение цены.
`comment / occurred_at`	`string`	Комментарий необязателен. `occurred_at` — действительная локальная дата операции не позже текущего момента; пропущенное поле означает текущее время.

Отдельные обязательства и цена посещения

Ожидание, его реальная оплата и общая цена посещения — разные действия. Для уменьшения суммы уже частично оплаченного платежа используйте явное изменение обязательства, а для цены посещения — save_booking_price. Сумма не может стать меньше уже закрытой оплатой или списанием.

Параметр	Формат	Назначение и ограничения
`title / category_id / comment`	`string / integer / string`	Назначение, необязательная денежная категория нужного направления и комментарий. При изменении передавайте сохраняемые текстовые поля явно; пропущенные значения не являются универсальным PATCH.
`confirmed`	`boolean`	Для отдельного приходного обязательства `true` означает подтверждённый долг, `false` — ожидание. Отменить подтверждение можно только в разрешённом неоплаченном состоянии. Расходное обязательство отражает ожидаемый расход.
`due_at / occurred_at`	`date / datetime`	`due_at` — срок оплаты, в том числе будущий. `occurred_at` — момент изменения условий, не позже текущего. Ручной срок хранится в истории и защищён от автоматического пересчёта расписания.
`id / version`	`integer`	При изменении передайте также исходные `direction, currency, client_id` и полную новую сумму. Их смена запрещена; версия относится к обязательству, а не к денежной оплате.
`booking_id`	`integer`	`save_obligation` для открытого приходного расчёта посещения задаёт срок `due_at`, а не переписывает цену. При ссылке на посещение нужны его ID, валюта и актуальная версия существующего обязательства. Для цены используется отдельный метод.
`amount / price_version / reason`	`string / integer / string`	У `save_booking_price` сумма может быть нулевой; передавайте актуальную `price_version` из посещения и необязательную причину до 4000 символов. Изменение обновляет общую цену и финансовый расчёт атомарно.
`reason`	`string`	У `skip_obligation` причина необязательна. Действие предназначено для отдельного неоплаченного ожидания; пропуск не удаляет историю и не отменяет фактические деньги.

Редактирование, замена и удаление операций

Удаление финансовой операции означает отмену с сохранением истории. Не отправляйте DELETE и не создавайте отрицательный платёж. Сначала перечитайте актуальную операцию; учитывайте ограничения minimum_amount, latest_occurred_at, edit_metadata_only и связи, возвращаемые журналом.

Параметр	Формат	Назначение и ограничения
`category_id / method_id / comment / reason`	`integer / integer / string / string`	`edit_operation` принимает допустимые категорию, способ оплаты, комментарий и причину. `rows/allocations/replacement` в этом методе запрещены; поля клиента, посещения, валюты, направления и источника не меняются.
`amount / occurred_at`	`string / datetime`	Действующий приход вида `cash/opening`, включая оплату услуги с распределениями, можно менять через `edit_operation` с сохранением ID в пределах `minimum_amount`, `latest_occurred_at` и последующих связей. Зачёт, списание, расход или возврат меняют сумму/дату через `correct_operation`; при закрытом расчёте учитывайте `edit_metadata_only`.
`replacement`	`object`	Полный объект нового `save_operation` внутри `correct_operation`: направление, категория, валюта, строки, клиент/посещение и распределения. Прежняя операция получает `state=replaced`, новые ID возвращаются в `operation_ids`. Историческая строка остаётся в истории.
`cancel`	`boolean`	`correct_operation` с `cancel=true` переводит операцию в `cancelled` и освобождает её распределения в общей транзакции. Необязательная причина до 4000 символов сохраняется в истории.
`cancel_dependents / preview_fingerprint`	`boolean / string`	Для использованного источника сначала вызовите `cancellation_preview`. Проверьте `operations, releases, price_effects, price_changes`; затем отправьте `cancel=true, cancel_dependents=true` и `preview_fingerprint` из ответа. Устаревший отпечаток даёт `1385`.
`id / version`	`integer`	Версия всегда актуальной операции. Отменённые, заменённые и полностью освобождённые исторические версии доступны для чтения; не используйте их как цель нового редактирования.

Расписания и синхронизация ожиданий

Расписание создаёт обязательства, а не оплачивает их. Сохранение существующего шаблона пересчитывает будущие автоматические ожидания, сохраняя оплаты, пользовательские отмены, удаления и ручные условия. Один период сохраняет ID в журнале и ожидаемых платежах; изменение старого месячного расписания не создаёт второй долг за тот же месяц.

Параметр	Формат	Назначение и ограничения
`start_on / recurrence_start`	`YYYY-MM-DD`	При создании обязательна исходная `start_on`. При изменении она остаётся прежней, а новую дату первого вхождения передают как `recurrence_start`. Валюта, направление и клиент существующего шаблона не меняются.
`recurrence_rule`	`string`	Правило — до 1024 символов. Частоты `FREQ=DAILY/WEEKLY/MONTHLY/YEARLY`, необязательный `INTERVAL`, окончание `COUNT` либо `UNTIL`. `INTERVAL` и `COUNT` — целые от 1 до 99999. `BYDAY=MO,TU,...` разрешён только с WEEKLY; `BYMONTHDAY=1,...,31` — только с MONTHLY. Остальные сочетания отклоняются `1381`.
`UNTIL`	`YYYYMMDD \| YYYYMMDDTHHmmss \| YYYYMMDDTHHmmssZ`	Граница включительна. С `Z` это абсолютный момент UTC с учётом зоны организации и DST; без `Z` — локальное время, а только дата включает весь локальный день. Например, `20261029T180000Z` в Токио означает 30 октября 03:00; локальный `end_on` равен 30 октября.
`recurrence_exdates`	`array, YYYY-MM-DD`	Массив максимум из 1000 локальных календарных дат без времени. Исключённые даты не создают ожиданий; изменение правила не переписывает уже защищённые экземпляры.
`paused`	`boolean`	Приостановка отменяет будущие автоматические платежи, если по ним не было оплат или ручных изменений. Оплаченные, изменённые и отменённые пользователем платежи сохраняются. При возобновлении подходящие даты восстанавливаются без дублей. Дни строго между приостановкой и возобновлением не начисляются, даже при переносе начала назад; сами граничные дни сохраняются. Даты считаются в часовом поясе организации: выключение и включение в один день не пропускает платёж. Перенос начала назад достраивает остальные допустимые периоды по окончательному правилу.
`day_of_month / interval_months / end_on`	`integer / integer / YYYY-MM-DD`	Совместимость прежнего месячного контракта без `recurrence_rule`: день 1–31, интервал 1–120 месяцев, необязательное окончание. Недостающее число переносится на конец месяца. Новые обычные MONTHLY-правила пропускают отсутствующее число; не передавайте оба контракта одновременно.
`to`	`YYYY-MM-DD`	Минимальный горизонт — локальное сегодня плюс 30 дней включительно; более поздний `to` расширяет его. При отсутствии открытого будущего платежа создаётся ближайший допустимый повтор даже дальше горизонта. Пакет — до 240 вхождений; до завершения повторяйте тот же запрос с прежним `to`. Ключ периода исключает дубли.
`next_payment_on`	`YYYY-MM-DD \| null`	Поле только для чтения: ближайший непогашенный платёж начиная с локального сегодня. Это не внутренний курсор. Чтение само не материализует ожидания.

Категории и способы оплаты

Управление справочниками использует save_category и save_method, а не общий CRUD. Архивирование и восстановление сохраняют существующие финансовые связи.

Параметр	Формат	Назначение и ограничения
`id / version`	`integer`	При создании отсутствуют; при изменении, архивировании и восстановлении передаются из справочника. Для системной записи сохраняется логический системный ID.
`name / direction`	`string / income \| expense`	Имя обязательно, до 255 символов. У новой категории обязательно направление. Системные названия/смысл и направление существующей категории не переопределяются произвольно.
`archived`	`boolean`	`true` архивирует, `false` восстанавливает. Передавайте имя записи и актуальную версию вместе с флагом; это полноценное сохранение.

Подбор оплаты, исторический срез и экспорт

Эти параметры используются только в соответствующих режимах чтения; они не заменяют проверку остатка в транзакции записи.

Параметр	Формат	Назначение и ограничения
`for_payment / as_of`	`boolean / datetime`	Для `obligations/booking_summary` режим оплаты добавляет `allocation_limit`; для `client_balance` требует клиента и валюту и возвращает `available_to_allocate` на дату действия.
`correction_id / version / for_writeoff`	`integer / integer / boolean`	При подборе новой оплаты вместо существующей передайте ID и версию исправляемой операции; лимиты исключают её прежнее распределение. `for_writeoff=true` разрешает только подтверждённый долг на дату действия.
`for_refund / client_id / currency`	`boolean / integer / string`	У `operations` режим `for_refund=true` требует клиента и валюту; необязательны `booking_id/as_of`. Возвращает допустимые источники с лимитом на дату возврата; несовместим с `include_expected=true`, расходным направлением и состоянием кроме `posted`.
`correction_version / booking_id`	`integer / integer`	При подборе источника исправляемого возврата передайте `correction_id` и `correction_version` либо `version`. Клиент, валюта и посещение должны совпадать с исправляемым возвратом.
`as_of`	`date / datetime`	В отчёте `from/to` задают период, а `as_of` — границу исторического расчёта остатков и распределений. Денежный приход, стоимость оказанных услуг, аванс, долг и ожидаемый расход — разные показатели, не взаимозаменяемые суммы.
`scope`	`operations \| reports`	`operations` экспортирует весь выбранный журнал, включая ожидания при соответствующем флаге; `reports` — итоги и срезы отчёта. CSV находится в JSON-поле `content`, кодировка UTF-8, разделитель — точка с запятой. Заголовки, статусы, виды операций и валюты представлены понятными названиями на языке запроса; технические ID и ключи групп не выгружаются. Даты записаны как ДД.ММ.ГГГГ ЧЧ:ММ:СС в часовом поясе организации; у связанных визитов есть отдельная дата. В русской выгрузке десятичный разделитель суммы — запятая, в английской — точка. Для автоматической обработки с идентификаторами используйте обычные JSON-чтения.

Поля ответов

Методы возвращают JSON-конверт. Дополнительные поля зависят от action; не подменяйте ID операции ID обязательства или шаблона.

Поле ответа	Формат	Назначение и ограничения
`ok / data`	`boolean / object`	Успех: `ok=true`, результат внутри `data`. У `save_obligation/save_recurring/edit_operation` есть свой `data.id`; у `save_operation` фактической оплаты используются массивы ID.
`code / message`	`integer / string`	При отказе: `ok=false`, числовой `code` и локализованный `message`. Не используйте текст сообщения как стабильный идентификатор ошибки.
`operation_ids / obligation_ids`	`integer[]`	У POST с ключом запроса — ID созданных/затронутых операций и обязательств. Разделённая оплата возвращает несколько операций. Пустой массив допустим.
`request_id / replayed`	`string / boolean`	Возвращаются у изменений с ключом запроса. `replayed=false` означает первое выполнение, `true` — сохранённый результат успешного повтора.
`items / total / page / page_size`	`array / integer / integer / integer`	Постраничные списки используют эти поля. У справочников, истории, расписаний и пакетной сводки посещений основное поле — `items`; общей пагинации для них нет.
`row_type / kind / state`	`string`	В объединённом журнале `row_type=operation/obligation`. Виды операций: `cash/balance/writeoff/opening`; состояния операций: `posted/cancelled/replaced`; обязательств: `open/cancelled/skipped`.
`paid / written_off / remaining`	`string`	Оплачено деньгами/авансом, списано и ещё осталось. У закрытого обязательства остаток равен нулю; история платежей сохраняется. У одного ожидания одинаковый ID в журнале и списке обязательств.
`available / reserved / debt / overdue`	`string`	Свободный аванс, зарезервированная оплата будущих услуг, подтверждённый долг и его просроченная часть. Значения группируются по валюте; они не являются новым денежным приходом.
`complete / generated / cursor / synced_until`	`boolean / integer / string / date`	Завершённость пакета, число созданных ожиданий, непрозрачный курсор и локальная дата горизонта. `cursor` — поле ответа: сравнивайте его между незавершёнными пакетами для контроля продвижения; передавать его на вход не требуется. Не вычисляйте из него дату следующего платежа.
`filename / mime / content`	`string`	Имя файла, MIME и текст CSV. Файл формируется из `data.content`; отдельного бинарного ответа нет.

Ошибки финансовых действий

Финансовый диапазон — 1381–1399. Проверки модуля, тарифа и разрешений также могут вернуть коды общего контракта модулей. После конфликта перечитайте актуальные данные, а после сетевого сбоя повторяйте исходный запрос с тем же ключом.

Код	Область	Причина и действие
`31`	`API key`	API-ключ разрешает только чтение. Для POST нужен ключ с правом записи и соответствующие права пользователя.
`1367`	`read_only`	Дополнительная проверка запрещает изменение ключом «только чтение». Для изменения нужен ключ с правом записи и соответствующие права пользователя.
`1381`	`payload`	Неверные поля, сумма, валюта, дата, структура или сочетание RRULE. Исправьте входные данные.
`1382`	`Authorization`	Недоступный контекст пользователя или попытка подменить организацию. Проверьте авторизацию и организацию текущей сессии или API-ключа.
`1383`	`request_id`	Этот request_id уже использован с другим телом. Для нового действия нужен новый ключ.
`1384`	`id`	Ссылка на недоступного клиента, посещение, справочник или финансовую сущность. Перечитайте ID.
`1385`	`version`	Данные или отпечаток предварительного просмотра изменились. Перечитайте сущность и повторно проверьте действие.
`1386`	`available_to_allocate`	Не хватает свободного аванса на дату действия. Проверьте доступный остаток.
`1387`	`remaining`	Распределение превышает остаток или новая сумма ниже закрытой оплаты/списания.
`1388`	`client_id / currency / direction`	Не совпадают клиент, валюта, направление или неизменяемые связи.
`1389`	`has_dependents`	Действие ограничено связанными оплатами, возвратами или закрытым расчётом. Сначала исправьте зависимости.
`1390`	`confirmed`	Подтверждённый долг нельзя пропустить как необязательное ожидание.
`1391`	`source_operation_id`	Недопустимый источник, сумма или контекст возврата. Повторно подберите источник и проверьте цену.
`1392`	`is_system`	Нельзя произвольно менять системное имя/смысл категории или способа оплаты.
`1393`	`POST`	Изменение отправлено не методом POST.
`1394`	`archived`	Категория или способ архивированы. Выберите действующую запись либо восстановите справочник.
`1395`	`complete`	Сначала завершите синхронизацию регулярных ожиданий, затем изменяйте расписание.
`1396`	`occurred_at`	Фактическое действие не может быть в будущем. Задайте будущий срок у ожидания.
`1397`	`paid / written_off`	Нельзя пропустить оплату посещения или уже частично оплаченный платёж. Явно измените цену/сумму.
`1398`	`state`	Историческая версия доступна только для чтения. Откройте актуальную операцию.
`1399`	`request_id`	Сохранение не завершилось из-за внутренней ошибки. Безопасно повторите исходное действие с тем же ключом.

Примеры последовательностей

ID условные: клиент 501; категории 101=client_advance, 102=service_payment, 103=rent, 104=client_refund; способы 201=cash, 202=card. Замените их значениями текущей организации из context. ID 1001… и 2001 иллюстрируют результаты сохранений; берите реальные ID из ответов, а версии — из свежего чтения. Для серверных запросов добавьте выбранный заголовок API-ключа; также можно использовать авторизованную сессию кабинета.

1. Приход двумя способами и свободная предоплата

Две денежные строки создают две операции на общую сумму 1000.00. Без посещения и распределений они остаются авансом клиента. У ответа фактической оплаты нет единого data.id.

Запросы и пример ответа

GET /api/?mod=finance&action=context

POST /api/?mod=finance&action=save_operation
Content-Type: application/json

{
	"request_id": "docs-finance-split-01",
	"direction": "income",
	"category_id": 101,
	"client_id": 501,
	"currency": "RUB",
	"rows": [
		{
			"source": "money",
			"amount": "300.00",
			"method_id": 201
		},
		{
			"source": "money",
			"amount": "700.00",
			"method_id": 202
		}
	]
}

{
	"ok": true,
	"data": {
		"operation_ids": [
			1001,
			1002
		],
		"obligation_ids": [],
		"request_id": "docs-finance-split-01",
		"replayed": false
	}
}

2. Отдельное ожидание и частичная оплата

Создано ожидание 1000.00, затем отдельно получено 400.00. В примере новая оплата имеет ID 1003; остаток обязательства — 600.00. Создание ожидания само денег не добавляет.

Запросы и пример ответа

POST /api/?mod=finance&action=save_obligation
Content-Type: application/json

{
	"request_id": "docs-finance-obligation-01",
	"direction": "income",
	"title": "Оплата дополнительной услуги",
	"category_id": 102,
	"client_id": 501,
	"currency": "RUB",
	"amount": "1000.00"
}

{
	"ok": true,
	"data": {
		"id": 2001,
		"operation_ids": [],
		"obligation_ids": [
			2001
		],
		"request_id": "docs-finance-obligation-01",
		"replayed": false
	}
}

POST /api/?mod=finance&action=save_operation
Content-Type: application/json

{
	"request_id": "docs-finance-partial-01",
	"direction": "income",
	"category_id": 102,
	"client_id": 501,
	"currency": "RUB",
	"rows": [
		{
			"source": "money",
			"amount": "400.00",
			"method_id": 201
		}
	],
	"allocations": [
		{
			"obligation_id": 2001,
			"amount": "400.00"
		}
	]
}

3. Зачёт прежнего аванса без нового прихода

После проверки доступного аванса и лимита обязательства направьте 100.00 из исходной операции 1001 на обязательство 2001. Это отдельная операция вида balance; остаток становится 500.00, денежный приход не увеличивается.

Запросы и пример ответа

GET /api/?mod=finance&action=client_balance&client_id=501&currency=RUB&for_payment=true

GET /api/?mod=finance&action=obligations&client_id=501&currency=RUB&outstanding_only=true&for_payment=true

POST /api/?mod=finance&action=allocate
Content-Type: application/json

{
	"request_id": "docs-finance-allocate-01",
	"client_id": 501,
	"currency": "RUB",
	"source_operation_id": 1001,
	"allocations": [
		{
			"obligation_id": 2001,
			"amount": "100.00"
		}
	]
}

4. Изменение свободного источника, возврат и отмена оплаты

У ещё не использованной операции 1002 увеличена сумма с 700.00 до 800.00; затем из неё возвращено 200.00. Отдельный запрос отменяет частичную оплату 1003 из примера 2. Для использованного источника с зависимостями сначала требуется cancellation_preview и согласование каскада.

Запросы и пример ответа

POST /api/?mod=finance&action=edit_operation
Content-Type: application/json

{
	"request_id": "docs-finance-edit-01",
	"id": 1002,
	"version": 1,
	"currency": "RUB",
	"amount": "800.00",
	"category_id": 101,
	"method_id": 202
}

POST /api/?mod=finance&action=save_operation
Content-Type: application/json

{
	"request_id": "docs-finance-refund-01",
	"direction": "expense",
	"category_id": 104,
	"client_id": 501,
	"source_operation_id": 1002,
	"currency": "RUB",
	"rows": [
		{
			"source": "money",
			"amount": "200.00",
			"method_id": 202
		}
	]
}

POST /api/?mod=finance&action=correct_operation
Content-Type: application/json

{
	"request_id": "docs-finance-cancel-01",
	"id": 1003,
	"version": 1,
	"cancel": true,
	"reason": "Ошибочно зарегистрированная оплата"
}

5. Расписание расходов, журнал и выгрузка

Создаётся три месячных ожидания по 10000.00. Если complete=false, повторяют тот же запрос синхронизации с прежним to. Чтения показывают ожидания и отчёт; выгрузка возвращает CSV внутри JSON. Фактический расход появится только после отдельной оплаты.

Запросы и пример ответа

POST /api/?mod=finance&action=save_recurring
Content-Type: application/json

{
	"request_id": "docs-finance-recurring-01",
	"name": "Аренда помещения",
	"direction": "expense",
	"category_id": 103,
	"currency": "RUB",
	"amount": "10000.00",
	"start_on": "2026-11-01",
	"recurrence_rule": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=1;COUNT=3",
	"recurrence_exdates": [],
	"paused": false
}

POST /api/?mod=finance&action=sync_regular
Content-Type: application/json

{
	"to": "2027-01-31"
}

GET /api/?mod=finance&action=recurring

GET /api/?mod=finance&action=obligations&direction=expense&outstanding_only=true&from=2026-11-01&to=2027-01-31

GET /api/?mod=finance&action=reports&from=2026-11-01&to=2027-01-31

GET /api/?mod=finance&action=export&scope=operations&include_expected=true&from=2026-11-01&to=2027-01-31

Исходящие финансовые события

Доступ через API-ключи и исходящая доставка — разные возможности. Финансовые события finance_operation, finance_obligation, finance_recurring, finance_category, finance_method доставляются по общим настройкам веб-хуков организации и правилам тарифа. Они содержат причину cause, изменённые поля и снимки before/after; обработчик должен учитывать повторные доставки и порядок событий. Наличие события не означает успешную HTTP-доставку.

Формат и доставка веб-хуков