Справочник API

Все маршруты — от адреса вашей CRM (https://<адрес CRM>), только HTTPS. Ключ — в заголовке Authorization: Bearer tk_<key_id>_<secret>, право ключа — rental:site. Ниже — то же, что в файле OpenAPI; пакет @type/site-client даёт к этим маршрутам типизированные методы.

Версия схемы: 0.1.0 · OpenAPI (JSON)

Маршруты

POST /booking-requests
GET /groups
GET /legacy-urls
GET /occupancy
GET /photos/{account_id}/{product_id}/{file}
GET /ping
GET /prices
GET /quote
GET /units
GET /units/{unit_id}

POST `/booking-requests`

/api/modules/rental/site/booking-requests

Заявка с формы сайта (ключ проверяется раньше полей: без ключа — 401, а не 422) → сделка-бронь на этапе «Заявка», источник site, с расчётом цены. Повтор request_id — тот же ответ. Занятые даты, блокировка, мин. срок или гостей больше максимума — 422 rental_unavailable.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Тело запроса

Схема: SiteBookingRequestIn

Ответы

Код	Схема	Описание
`201`	SiteBookingRequestOut
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`		`rental_unavailable` (`violations`) или ошибка полей
`429`		`too_many_attempts`, `Retry-After`

GET `/groups`

/api/modules/rental/site/groups

Группы (районы) с числом неархивных объектов — фильтр каталога.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	массив SiteGroup
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/legacy-urls`

/api/modules/rental/site/legacy-urls

Старые адреса товаров WooCommerce → объект и его ЧПУ: таблица 301 в плагине.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	массив SiteLegacyUrl
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/occupancy`

/api/modules/rental/site/occupancy

Занятые интервалы по объектам (подтверждённые брони и блокировки), без гостей и сумм; особые даты периода — для подсветки в календаре.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`date_from`	query	string (date)	да
`date_to`	query	string (date)	да	Не включительно; не больше 400 дней
`unit_ids`	query	массив string (uuid) \| null
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SiteOccupancyOut
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`		`invalid_period` — больше 400 дней
`429`		`too_many_attempts`, `Retry-After`

GET `/photos/{account_id}/{product_id}/{file}`

/api/modules/rental/site/photos/{account_id}/{product_id}/{file}

Постоянная публичная ссылка на фото объекта (без ключа, для <img> на сайте): 302 на временную ссылку превью WebP 1920 (без EXIF), Cache-Control: public, max-age=3000. Оригинал наружу не отдаётся: перенесённое фото, у которого превью ещё строится, — 503 с Retry-After: 60. Только фото неархивных объектов аккаунта с включённым модулем; иначе 404.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.
`account_id`	path	string (uuid)	да
`product_id`	path	string (uuid)	да
`file`	path	string	да

Ответы

Код	Схема	Описание
`302`		На превью WebP в хранилище
`404`		Нет фото
`422`	HTTPValidationError	Validation Error
`503`		`photo_processing` — превью ещё строится, `Retry-After`

GET `/ping`

/api/modules/rental/site/ping

Проверка подключения плагина: аккаунт, валюта, языки текстов, время заезда и выезда.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SiteInfo
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/prices`

/api/modules/rental/site/prices

Цена и доступность всех объектов на даты — фильтр каталога «цена за выбранные даты».

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`check_in`	query	string (date)	да
`check_out`	query	string (date)	да
`guests`	query	integer
`group_id`	query	string (uuid) \| null
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SitePricesOut
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/quote`

/api/modules/rental/site/quote

Калькулятор: цена каждой ночи, скидки каталога, итог; нарушения (занято, мин. срок, гостей больше максимума). Тот же расчёт, что в CRM.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`unit_id`	query	string (uuid)	да
`check_in`	query	string (date)	да
`check_out`	query	string (date)	да
`guests`	query	integer
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SiteQuoteOut
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/units`

/api/modules/rental/site/units

Все неархивные объекты с текстами на lang, фото по постоянным ссылкам, удобствами и базовой ценой. updated_at — версия для кэша плагина.

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`lang`	query	`ro` · `en` · `ru`		Язык текстов; нет текста — румынский
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SiteUnitsOut
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

GET `/units/{unit_id}`

/api/modules/rental/site/units/{unit_id}

Ключ API с правом rental:site.

Параметры

Имя	Где	Тип	Обяз.	Описание
`unit_id`	path	string (uuid)	да
`lang`	query	`ro` · `en` · `ru`		Язык текстов; нет текста — румынский
`x-type-visitor-ip`	заголовок	string \| null		IP посетителя сайта

Ответы

Код	Схема	Описание
`200`	SiteUnit
`400`		`api_key_misplaced` — ключ в query, cookie или теле
`401`		`api_key_invalid` — ключ не принят (причина — в журнале сервера)
`403`		`scope_missing` — нет права `rental:site`; `scope_unavailable` — модуль выключен
`404`		`not_found` — нет объекта или он в архиве
`422`	HTTPValidationError	Validation Error
`429`		`too_many_attempts`, `Retry-After`

Схемы

`Application`

значения: auto · manual

`AppliedDiscount`

Сработавшая скидка каталога (§19.10): на строку — её доля, в итогах — всего.

Поле	Тип	Обяз.	Описание
`amount`	string	да	На сколько уменьшила сумму (с TVA, как `gross`)
`application`	Application	да
`discount_id`	string (uuid)	да
`kind`	DiscountKind	да
`name`	string	да

`DiscountKind`

значения: line · deal

`HTTPValidationError`

Поле	Тип	Обяз.	Описание
`detail`	массив ValidationError

`I18n3`

Тексты на языках сайта: ro (основной), en, ru.

Поле	Тип	Обяз.	Описание
`en`	string
`ro`	string
`ru`	string

`Night`

Поле	Тип	Обяз.
`base`	string	да
`date`	string (date)	да
`price`	string	да
`special_date_id`	string (uuid) \| null
`special_name`	string \| null

`SiteBookingRequestIn`

Заявка с формы сайта → сделка-бронь на этапе «Заявка» с расчётом цены. Клиент — по телефону или e-mail (найден — привязывается, нет — создаётся контакт). Нужен телефон или e-mail. Антиспам: hp (скрытое поле-ловушка) непустое или elapsed_ms < 3000 — ответ как при успехе, но сделка не создаётся. Повтор с тем же request_id (досылка из очереди плагина) не создаёт вторую сделку и возвращает тот же ответ.

Поле	Тип	Обяз.	Описание
`check_in`	string (date)	да
`check_out`	string (date)	да
`consent`	`true`	да	Согласие на обработку персональных данных
`elapsed_ms`	integer ≥ 0	да	Сколько форма была открыта до отправки, мс
`email`	string (email) \| null
`guests`	integer ≥ 1, ≤ 100		По умолчанию: `1`.
`hp`	string ≤ 200		Поле-ловушка: скрыто от людей, должно быть пустым
`lang`	`ro` · `en` · `ru`		По умолчанию: `"ro"`.
`message`	string \| null
`name`	string ≥ 1, ≤ 200	да
`page_url`	string \| null
`phone`	string \| null
`request_id`	string (uuid)	да	UUID заявки, создаёт плагин — идемпотентность
`unit_id`	string (uuid)	да
`utm`	object → string \| null

`SiteBookingRequestOut`

Поле	Тип	Обяз.
`currency`	string	да
`nights`	integer	да
`request_id`	string (uuid)	да
`status`	`"received"`	да
`total`	string	да

`SiteDiscount`

Поле	Тип	Обяз.	Описание
`ends_on`	string (date) \| null	да	Последний день действия; `null` — бессрочно
`name`	string	да
`value`	string	да
`value_type`	`percent` · `fixed`	да	`fixed` — сумма за ночь

`SiteGroup`

Поле	Тип	Обяз.
`id`	string (uuid)	да
`name`	string	да
`units_count`	integer	да

`SiteInfo`

Поле	Тип	Обяз.	Описание
`account_name`	string	да
`check_in_time`	string	да
`check_out_time`	string	да
`currency`	string	да
`key_name`	string	да
`languages`	массив `ro` · `en` · `ru`	да	Языки, на которых есть тексты объектов
`timezone`	string	да

`SiteLegacyUrl`

Поле	Тип	Обяз.	Описание
`gone`	boolean	да	Объект удалён — ответить 410 Gone
`lang`	string	да
`path`	string	да	Путь старого адреса (`/ro/product/<slug>/`): товар WooCommerce или прежний слаг объекта — ключ для 301
`slug`	string \| null	да	ЧПУ объекта на языке старого адреса; `null` — объект удалён
`unit_id`	string (uuid)	да
`url`	string	да	Старый адрес: товар WooCommerce или путь прежнего слага

`SiteOccupancyOut`

Поле	Тип	Обяз.
`date_from`	string (date)	да
`date_to`	string (date)	да
`special_dates`	массив SiteSpecialDay	да
`units`	массив SiteUnitBusy	да

`SitePhoto`

Поле	Тип	Обяз.	Описание
`position`	integer	да
`url`	string	да	Постоянная публичная ссылка `/api/modules/rental/site/photos/{account_id}/{product_id}/{file}` (без ключа)

`SitePrice`

Поле	Тип	Обяз.	Описание
`available`	boolean	да
`per_night`	string \| null	да	Средняя цена ночи с учётом скидок
`per_night_before`	string \| null	да	Средняя цена ночи до скидок
`subtotal`	string \| null	да	Итог до скидок; `null` — даты недоступны
`total`	string \| null	да	Итог после скидок; `null` — даты недоступны
`unit_id`	string (uuid)	да
`violations`	массив SiteViolation	да

`SitePricesOut`

Поле	Тип	Обяз.
`check_in`	string (date)	да
`check_out`	string (date)	да
`currency`	string	да
`guests`	integer	да
`nights`	integer	да
`units`	массив SitePrice	да

`SiteQuoteOut`

Поле	Тип	Обяз.	Описание
`available`	boolean	да	Нет блокирующих нарушений — можно отправить заявку
`check_in`	string (date)	да
`check_out`	string (date)	да
`currency`	string	да
`discounts`	массив AppliedDiscount	да
`guests`	integer	да
`nights`	integer	да
`per_night`	массив Night	да
`subtotal`	string	да
`total`	string	да
`unit_id`	string (uuid)	да
`violations`	массив SiteViolation	да

`SiteRange`

Поле	Тип	Обяз.	Описание
`end`	string (date)	да	Не включительно: день выезда свободен для заезда
`start`	string (date)	да

`SiteSpecialDay`

Поле	Тип	Обяз.	Описание
`end`	string (date)	да	Включительно
`min_nights`	integer \| null	да
`name`	string	да
`start`	string (date)	да
`unit_ids`	массив string (uuid) \| null	да	`null` — все объекты

`SiteUnit`

Поле	Тип	Обяз.	Описание
`address`	string \| null	да
`amenities`	массив string	да	Удобства на языке `lang` (нет перевода — румынский), по порядку справочника
`area_m2`	string \| null	да	Площадь, м²
`base_price`	string	да	Цена ночи без скидок — «старая» при `discount`
`bathrooms`	integer	да
`beds`	integer \| null	да
`check_in_time`	string	да
`check_out_time`	string	да
`currency`	string	да
`description`	string	да
`discount`	SiteDiscount \| null	да	Скидка в `price`; `null` — без скидки
`district`	string \| null	да
`floor`	integer \| null	да	Этаж
`group_id`	string (uuid) \| null	да
`group_name`	string \| null	да
`has_balcony`	boolean	да
`has_living`	boolean	да
`has_terrace`	boolean	да
`id`	string (uuid)	да
`lang`	`ro` · `en` · `ru`	да	Язык текстов; нет текста на языке — румынский
`lat`	number \| null	да
`lng`	number \| null	да
`max_guests`	integer	да
`name`	string	да
`names`	I18n3	да
`photos`	массив SitePhoto	да
`position`	integer	да
`price`	string	да	Цена ночи («от») с безусловной скидкой на объект, действующей сегодня; особые даты не входят. Нет скидки — равна `base_price`
`rooms`	string \| null	да
`rooms_count`	integer \| null	да	Комнат; 0 — студия
`slug`	string	да	ЧПУ на языке `lang` (нет — румынский); хранится, уникален среди объектов, при переименовании не меняется
`slugs`	object → string	да	ЧПУ на всех языках — для hreflang
`updated_at`	string (date-time)	да

`SiteUnitBusy`

Поле	Тип	Обяз.	Описание
`busy`	массив SiteRange	да	Подтверждённые брони и блокировки, слитые в интервалы; без гостей и сумм. Заявки дат не занимают и не показываются
`unit_id`	string (uuid)	да

`SiteUnitsOut`

Поле	Тип	Обяз.	Описание
`lang`	`ro` · `en` · `ru`	да
`units`	массив SiteUnit	да	Объекты без архивных, по порядку
`updated_at`	string (date-time) \| null	да	Последнее изменение — версия кэша

`SiteViolation`

Нарушения расчёта для сайта: без tentative_overlap (заявки других гостей не видны).

Поле	Тип	Обяз.	Описание
`blocking`	boolean	да	Бронь не сохранится (иначе — предупреждение)
`code`	`dates_invalid` · `min_nights` · `max_guests` · `occupied` · `tentative_overlap` · `blocked` · `unit_archived`	да
`params`	object

`ValidationError`

Поле	Тип	Обяз.
`ctx`	object
`input`	any
`loc`	массив string \| integer	да
`msg`	string	да
`type`	string	да

Справочник API

Маршруты

POST /booking-requests

Параметры

Тело запроса

Ответы

GET /groups

Параметры

Ответы

GET /legacy-urls

Параметры

Ответы

GET /occupancy

Параметры

Ответы

GET /photos/{account_id}/{product_id}/{file}

Параметры

Ответы

GET /ping

Параметры

Ответы

GET /prices

Параметры

Ответы

GET /quote

Параметры

Ответы

GET /units

Параметры

Ответы

GET /units/{unit_id}

Параметры

Ответы

Схемы

Application

AppliedDiscount

DiscountKind

HTTPValidationError

I18n3

Night

SiteBookingRequestIn

SiteBookingRequestOut

SiteDiscount

SiteGroup

SiteInfo

SiteLegacyUrl

SiteOccupancyOut

SitePhoto

SitePrice

SitePricesOut

SiteQuoteOut

SiteRange

SiteSpecialDay

SiteUnit

SiteUnitBusy

SiteUnitsOut

SiteViolation

ValidationError

POST `/booking-requests`

GET `/groups`

GET `/legacy-urls`

GET `/occupancy`

GET `/photos/{account_id}/{product_id}/{file}`

GET `/ping`

GET `/prices`

GET `/quote`

GET `/units`

GET `/units/{unit_id}`

`Application`

`AppliedDiscount`

`DiscountKind`

`HTTPValidationError`

`I18n3`

`Night`

`SiteBookingRequestIn`

`SiteBookingRequestOut`

`SiteDiscount`

`SiteGroup`

`SiteInfo`

`SiteLegacyUrl`

`SiteOccupancyOut`

`SitePhoto`

`SitePrice`

`SitePricesOut`

`SiteQuoteOut`

`SiteRange`

`SiteSpecialDay`

`SiteUnit`

`SiteUnitBusy`

`SiteUnitsOut`

`SiteViolation`

`ValidationError`