Перейти к содержанию

06. Локация

Версия 0.3.0
Количество листов

Оглавление

История изменений

№ Дата: 25.08.25 Автор: Демкович Александр RFC: RPL-1051 Версия: 0.1.0
Добавлено:
• Требование мультиязычности для “Заголовка” типа локации
• Требование мультиязычности для “Заголовка” удобства
• Требование мультиязычности для “Заголовка” опции удобства
• Локали для “06_5_1.1 Ошибки при выполнении проверки 06_5_1”
• Локали для “06_5_2.1 Ошибки при выполнении проверки 06_5_2”
• Локали для “06_5_3 Процедура создания Локации”.
№ 2 Дата: 11.09.25 Автор: Ляшук Андрей RFC: RPL-1288 Версия: 0.2.0
Добавлена:
• Португальская локаль для “06_5_1.1 Ошибки при выполнении проверки 06_5_1”
• Португальская локаль для “06_5_2.1 Ошибки при выполнении проверки 06_5_2”.
№ 3 Дата: 11.09.25 Автор: Ляшук Андрей RFC: RPL-1317 Версия: 0.3.0
Добавлена:
• Испанская локаль для “06_5_1.1 Ошибки при выполнении проверки 06_5_1”
• Испанская локаль для “06_5_2.1 Ошибки при выполнении проверки 06_5_2”.
№ 4 Дата: 24.09.25 Автор: Ляшук Андрей RFC: RPL-1086 Версия: 1.0.0
Добавлена:
• “06_5_4 Процедура обработки ссылки web_link”
• “06_5_5 Процедура обработки ссылки map_link”
• “06_5_6 Процедура обработки ссылки instagram_username”
• “06_5_7 Процедура обновления Локации”.

Изменено:
В “06_5_3 Процедуре создания Локации” этап “3”.
№ 5 Дата: 30.09.25 Автор: Ляшук Андрей RFC: RPL-1324 Версия: 1.1.0
Изменено:
В “06_5_3 Процедуре создания Локации” добавлено создание сообщения “Webhook event”.
№ 6 Дата: 05.04.26 Автор: Ляшук Андрей RFC: RPL-2002 Версия: 1.2.0
Добавлено:
• “06_5_8 Процедура изменения описания от ИИ-модели локации”
• “06_5_9 Процедура генерации описания от ИИ-модели”.

Изменено:
• В “3.2 Параметры Локации(locations)” добавлен параметр “ai_description”
• В “06_5_3 Процедура создания Локации” добавлена инициация “01.1.10_1.7_2 Процедура добавления записи в буфер отслеживания локаций, для которых генерируется ответ от ИИ-модели”, при успешной записи в буфер выполняется добавление сообщения в буфер “Создания описания локации для кампании ИИ-моделью OpenAI”.
№ 7 Дата: 05.02.26 Автор: Ляшук Андрей RFC: RPL-2275 Версия: 1.3.0
Изменено:
“06_5_8 Процедура изменения описания от ИИ-модели локации” добавлена инициации “02_2.5_1 Процедура создания и обновления сессии пользователя”.
№ 8 Дата: 20.02.26 Автор: Ляшук Андрей RFC: RPL-2423 Версия: 1.4.0
Изменено:
В “2.1 Параметры Тип локации(location_types)” добавлен параметр “placeholder_id”.
№9 Дата: 31.08.26 Автор:Ляшук Андрей RFC: RPL-2885 Версия: 1.5.0
Изменено:
В “06_5_3 Процедура создания Локации” добавлено изменение параметра “Отель” Бизнеса при создании Локации с Типом локации “Отель”.
№10 Дата: 29.09.26 Автор:Ляшук Андрей RFC: RPL-2929 Версия: 1.6.0
Изменено:
“06_5_6 Процедура обработки ссылки instagram_username” - имя в сервисе определяется согласно “02_3.2_14 Процедура определения имени в сервисе Instagram”.

1. Описание

Локацией является фактическое место проведения Кампании, которые организуются Представителем бизнеса.

Под локацией понимается объект недвижимости который характеризуется наличием адреса, географических координат и общим описанием объекта.

1_1 Типы локаций

Тип Описание
Отель Средство размещения гостей, состоящее из определенного количества номеров, имеющее единое руководство и предоставляющее набор услуг(минимум — заправка постелей, уборка номера и санузла).
Ресторан Предприятие общественного питания с широким ассортиментом блюд сложного приготовления, включая заказные и фирменные
Бар Предприятие общественного питания, оборудованное барной стойкой и реализующее в зависимости от специализации безалкогольные , горячие и прохладительные напитки, коктейли, холодные и горячие закуски и блюда в ограниченном ассортименте, покупные товары.

2. Данные Типа локации

2.1 Параметры Тип локации(location_types)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор id serial да да
Заголовок title varchar(255) да да Является переводимым.
Статус активности is_active boolean да нет
Идентификатор иконки icon_id int нет нет
Идентификатор плейсхолдера placeholder_id int нет нет

2.1_1 Предустановленные типы локаций

Тип Параметры
Отель id - 1; title - Hotel.
Ресторан id - 2 title - Restaurant.
Бар id - 3; title - Bar.

2.2 Параметры Удобства типа локации(location_type_amenity)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор типа локации location_type_id int да нет
Идентификатор удобства amenity_id int да нет

3. Данные локации

3.2 Параметры Локации(locations)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор id bigserial да да
Дата создания created_at timestamp да нет
Дата обновления updated_at timestamp нет нет
Дата удаления deleted_at timestamp нет нет
Дата архивации archived_at timestamp нет нет
Статус активности is_active boolean да нет
Идентификатор бизнеса business_id bigint да нет
Идентификатор типа локации location_type_id int да нет
Заголовок title varchar(255) да нет
Адрес address text да нет
Название аккаунта в Instagram instagram_username varchar(255) нет нет
Ссылка на локацию в Google maps map_link text нет нет
Ссылка на локацию в web-сервисе web_link text нет нет
Описание description text нет нет
Идентификатор города city_id int да нет
Идентификатор изображения cover_image_id bigint нет нет
Описание от ИИ-модели ai_description text нет нет

3.2 Параметры Удобства локации(location_amenitiy)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор id bigserial да да
Дата удаления deleted_at timestamp нет нет
Идентификатор локации location_id bigint да нет
Идентификатор удобства amenitiy_id serial да нет
Значение value json да нет

3.3 Параметры Избранной локации инфлюэнсера(influencer_favorite_propertry)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор локации location_id bigint да нет
Идентификатор инфлюэнсера user_id bigint да нет

4. Данные удобства

4.1 Параметры удобства(amenities)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор id serial да да
Тип type enum да нет Возможны следующие типы: 1 - Селект; 2 - Мультиселект; 3 - Булевый.
Заголовок title varchar(255) да да Является переводимым.
Иконка icon_id bigint нет нет

4.2 Параметры Опции удобства(amenity_options)

Название Параметр Формат Обяз. Уник. Примечание
Идентификатор id serial да да
Идентификатор удобства amenity_id int да нет
Заголовок title varchar(255) да нет Является переводимым.
Иконка icon_id bigint нет нет
Индексы Параметры
Уникальный индекс amenity_id, title

5. CRUD Локации

06_5_1 Процедура архивации Локации

API: POST /private/locations/{id}/archive

  1. Клиентской частью сервиса выполняется запрос “Archive location”.
  3. Если для “Локации”, которая была указана при инициации запроса, имеется “Дата архивации” на запрос “Archive location” возвращается ошибка “0601”;
  4. Если для “Локации”, которая была указана при инициации запроса, не имеется “Даты архивации” выполняется этап “3” данной процедуры.
  5. Выполняется:
  6. “Дата архивации” локации, которая была указана при инициации запроса, изменяется согласно текущей дате;

  7. Для каждой “Кампании” которая:

    1. Относится к “Локации”, которая была указана при инициации запроса;
    2. “Статус” которой “Активная”;

    “Статус” изменяется на “Приостановлена”.

  8. На запрос “Archive location” возвращается информация об успешной архивации локации.

06_5_1.1 Ошибки при выполнении проверки 06_5_1

Код ошибки Этап Локаль Текст ошибки
0601 2_a en “Location already archived (code: 0601)”
es "La propiedad ya se ha archivado (código: 0601)"
pt “Localização já arquivada (código: 0601)”
fr
06_5_2 Процедура разархивации Локации

API: POST /private/locations/{id}/unarchive

  1. Клиентской частью сервиса выполняется запрос “Unarchive location”.
  3. Если для “Локации”, которая была указана при инициации запроса, не имеется “Даты архивации” на запрос “Unarchive location” возвращается ошибка “0602”;
  4. Если “Локация” относится к “Типу локации”, “Статус активности” которого false на запрос “Unarchive location” возвращается ошибка “0603”;
  5. Если количество “Локаций”:
    1. Которые относятся к тому же “Бизнесу” к которому относится “Локация” для которой была инициирована данная процедура;
    2. Которые не имеют “Дату архивации”;

равно или более чем:

  1. Значение параметра “Количество активных локаций” персонального количества бесплатных коллабораций, если для данного “Бизнеса” имеется “Персональное количество активных локаций”;

  2. Значение параметра “quantity” настройки “Количество активных локаций по умолчанию”, если для данного “Бизнеса” не имеется “Персонального количество активных локаций”;

    на запрос “Unarchive location” возвращается ошибка “0605”.

  3. Если условия “2_a”, “2_b” или “2_c”не выполняются, выполняется этап “3” данной процедуры.

  4. Выполняется:
  5. “Дата архивации” локации, которая была указана при инициации запроса, удаляется.
  6. На запрос “Unarchive location” возвращается информация об успешной архивации локации.

06_5_2.1 Ошибки при выполнении проверки 06_5_2

Код ошибки Этап Локаль Текст ошибки
0602 2_a en “Location already unarchived (code: 0602)”
es "La propiedad ya se ha desarchivado (código: 0602)"
pt “Localização já retirada do arquivo (código: 0602)”
fr
0603 2_b en “Location type is not active (code: 0603)”
es "No está activo el tipo de propiedad (código: 0603)"
pt “O tipo de localização não está ativo (código: 0603)”
fr
0605 2_с en “You cannot unarchive the location because you are already using the maximum number of active locations (code: 0605)”
es "No puedes desarchivar la propiedad porque ya estás utilizando el número máximo de propiedades activas (código: 0605)"
pt “Não é possível retirar do arquivo a localização porque já está a utilizar o número máximo de localizações ativas (código: 0605)”
fr
06_5_3 Процедура создания Локации

API: POST /private/locations

  1. Клиентской частью сервиса выполняется запрос “Create location”.
  3. Если при выполнении запроса был указан “Тип локации”, “Статус активности” которого false на запрос “Create location” возвращается ошибка “0604”;
  4. Если количество “Локаций”:
    1. Которые относятся к тому же “Бизнесу” к которому относится “Локация” для которой была инициирована данная процедура;
    2. Которые не имеют “Дату архивации”;

равно или более чем:

  1. Значение параметра “Количество активных локаций” персонального количества бесплатных коллабораций, если для данного “Бизнеса” имеется “Персональное количество активных локаций”;

  2. Значение параметра “quantity” настройки “Количество активных локаций по умолчанию”, если для данного инфлюэнсера не имеется “Персонального количество бесплатных коллабораций”;

    на запрос “Create location” возвращается ошибка “0606”.

  3. Если условия “2_a” или “2_b” не выполняются, выполняется этап “3” данной процедуры.

  5. Если значение параметра “web_link”, который был указан при инициации данной процедуры начинается не с подстроки “http://” или “https://” выполняется “06_5_4 Процедура обработки ссылки web_link” с параметром “web_link” который был указан при выполнении запроса;
  6. Если значение параметра “map_link”, который был указан при инициации данной процедуры начинается не с подстроки “http://” или “https://” выполняется “06_5_5 Процедура обработки ссылки map_link” с параметром “map_link” который был указан при выполнении запроса;
  7. Если значение параметра “instagram_username”, который был указан при инициации данной процедуры начинается не с подстроки “http://” или “https://” выполняется “06_5_6 Процедура обработки ссылки instagram_username” с параметром “instagram_username” который был указан при выполнении запроса.
  8. Выполняется:
  9. Создание Локации с параметрами:
    1. web_link:
      1. Если при выполнении этапа “3” данной процедуры, процедура “06_5_4 Процедура обработки ссылки web_link”:
        1. Не была выполнена - значение параметра “web_link” который был указан при выполнении запроса;
        2. Была выполнена - значение параметра “web_link”, который был получен в результате выполнения процедуры 06_5_4.
    2. map_link:
      1. Если при выполнении этапа “3” данной процедуры, процедура “06_5_5 Процедура обработки ссылки map_link”:
        1. Не была выполнена - значение параметра “map_link” который был указан при выполнении запроса;
        2. Была выполнена - значение параметра “map_link”, который был получен в результате выполнения процедуры 06_5_5.
    3. instagram_username:
      1. Если при выполнении этапа “3” данной процедуры, процедура “06_5_6 Процедура обработки ссылки instagram_username”:
        1. Не была выполнена - значение параметра “instagram_username” который был указан при выполнении запроса;
        2. Была выполнена - значение параметра “instagram_username”, который был получен в результате выполнения процедуры 06_5_6.
    4. Которые были указаны при выполнении запроса.
  10. Выполняется добавление сообщения в очередь “Отправки событий в Make” с параметрами:
    1. event_type - Создание локации;
    2. entity_id - Идентификатор локации которая была создана на этапе “4_a” данной процедуры.
    1. “01.1.10_1.7_2 Процедура добавления записи в буфер отслеживания локаций, для которых генерируется ответ от ИИ-модели” с параметрами:
      1. location_id - Идентификатор локации, которая была создана на этапе “3_b” данной процедуры.
    2. Если “01.1.10_1.7_2 Процедура добавления записи в буфер отслеживания локаций, для которых генерируется ответ от ИИ-модели” была выполнена:
      1. Успешно, выполняется:
        1. Добавление сообщения “Локация” в очередь “Создания описания локации для кампании ИИ-моделью OpenAI” с параметрами:
        2. location_id - Идентификатор локации, которая была создана на этапе “3_b” данной процедуры;
        3. Этап “5” данной процедуры;
      2. Не успешно, выполняется этап “5” данной процедуры.
  12. “02_2.5_1 Процедура создания и обновления сессии пользователя” с параметрами:
    1. session_id - “X-Session-Id”, который был указан в заголовке запроса;
    2. user_id - Идентификатор пользователя который инициировал данную процедуру;
    3. action - Создание локации.
  13. Если “Тип локации” Локации, которая была создана на этапе “4_a” данной процедуры “Отель”, изменяются параметры Бизнеса, к которому относится данная Локация:
    1. Отель - true.
  14. На запрос “Create location” возвращается информация об успешном выполнении данной процедуры.

06_5_3.1 Ошибки при выполнении проверки 06_5_2

Код ошибки Этап Локаль Текст ошибки
0604 2_a_i en “Location type is not active (code: 0604)”
es "No está activo el tipo de propiedad (código: 0604)"
pt “O tipo de localização não está ativo (código: 0604)”
fr
0606 2_b en “You cannot create the location because you are already using the maximum number of active locations (code: 0606)”
es "No puedes crear la propiedad porque ya estás utilizando el número máximo de propiedades activas (código: 0606)"
pt “Não é possível criar a localização porque já está a utilizar o número máximo de localizações ativas (código: 0606)”
fr
  1. Выполняется инициации данной процедуры с параметрами:
  2. web_link.
  3. Выполняется GET запрос по адресу “https://{web_link}/”:
  4. Если запрос не был выполнен или выполнен и код ответа от 400 до 500:
    1. Выполняется GET запрос по адресу “http://{web_link}/”:
      1. Если запрос не был выполнен или выполнен и код ответа от 400 до 500 инициатору данной процедуры возвращается “{web_link}”;
      2. Если запрос был выполнен и код ответа от 200 до 399, инициатору данной процедуры возвращается “http://{web_link}/”.
  5. Если запрос был выполнен и код ответа от 200 до 399, инициатору данной процедуры возвращается “https://{web_link}/”.
  1. Выполняется инициации данной процедуры с параметрами:
  2. map_link.
  3. Инициатору данной процедуры возвращается “https://{map_link}/”.
06_5_6 Процедура обработки ссылки instagram_username
  1. Выполняется инициации данной процедуры с параметрами:
  2. instagram_username.
  3. Инициатору данной процедуры возвращается “https://www.instagram.com/{результат выполнения “02_3.2_14 Процедура определения имени в сервисе Instagram” с параметром “Значение” - “instagram_username”}/”.
06_5_7 Процедура обновления Локации

API: PUT /private/locations/{id}

  1. Клиентской частью сервиса выполняется запрос “Update location”.
  3. Если значение параметра “web_link”, который был указан при инициации данной процедуры, начинается не с подстроки “http://” или “https://” выполняется “06_5_4 Процедура обработки ссылки web_link” с параметром “web_link” который был указан при выполнении запроса;
  4. Если значение параметра “map_link”, который был указан при инициации данной процедуры, начинается не с подстроки “http://” или “https://” выполняется “06_5_5 Процедура обработки ссылки map_link” с параметром “map_link” который был указан при выполнении запроса;
  5. Если значение параметра “instagram_username”, который был указан при инициации данной процедуры, начинается не с подстроки “http://” или “https://” выполняется “06_5_6 Процедура обработки ссылки instagram_username” с параметром “instagram_username” который был указан при выполнении запроса.
  6. Выполняется изменение Локации с параметрами:
  7. web_link:
    1. Если при выполнении этапа “2” данной процедуры, процедура “06_5_4 Процедура обработки ссылки web_link”:
      1. Не была выполнена - значение параметра “web_link” который был указан при выполнении запроса;
      2. Была выполнена - значение параметра “web_link”, который был получен в результате выполнения процедуры 06_5_4.
  8. map_link:
    1. Если при выполнении этапа “2” данной процедуры, процедура “06_5_5 Процедура обработки ссылки map_link”:
      1. Не была выполнена - значение параметра “map_link” который был указан при выполнении запроса;
      2. Была выполнена - значение параметра “map_link”, который был получен в результате выполнения процедуры 06_5_5.
  9. instagram_username:
    1. Если при выполнении этапа “2” данной процедуры, процедура “06_5_6 Процедура обработки ссылки instagram_username”:
      1. Не была выполнена - значение параметра “instagram_username” который был указан при выполнении запроса;
      2. Была выполнена - значение параметра “instagram_username”, который был получен в результате выполнения процедуры 06_5_6.
  10. Которые были указаны при выполнении запроса.
06_5_8 Процедура изменения описания от ИИ-модели локации

API: PATCH /locations/{location_id}/ai-description

  1. Выполняется запрос “Update ai-description”:
  2. С параметрами:
    1. location_id;
  4. С телом запроса:
    1. description.
  5. Выполняется:
  6. Изменение “Описания от ИИ-модели” локации, для которой была инициирована данная процедура - “description”, который был получен при инициации данной процедуры.

  7. Для каждого “Представителя бизнеса”:

    1. Который относится к “Бизнесу”, к которому относится “Локация”, для которой была инициирована данная процедура;
    2. Для которого имеется подключение к веб-сокету.

    выполняется:

    1. Отправка сообщения в веб-сокет “Уведомления от сервиса Centrifugo” для канала “notification_{Идентификатор пользователя к которому относится “Представитель бизнеса”}” с параметрами:
      1. type - “description_for_campaign_generated”;
      2. data.location_id - “location_id”, который был указан при инициации данной процедуры.
      3. data.description - “description”, который был указан при инициации данной процедуры.
    2. Выполняется удаление записи из буфера “Отслеживания локаций, для которых генерируется ответ от ИИ-модели” ключ, которой соответствует значению параметра “location_id”, который был указан при инициации данной процедуры.
06_5_9 Процедура генерации описания локации от ИИ-модели для кампании

API: POST /private/campaigns/locations/{id}/ai-description

  1. Выполняется запрос “Generate AI description of location for campaign”:
  2. С параметрами:
    1. location_id;
  4. “01.1.10_1.7_2 Процедура добавления записи в буфер отслеживания локаций, для которых генерируется ответ от ИИ-модели” с параметрами:
    1. location_id - Идентификатор локации, которая была создана на этапе “3_b” данной процедуры.
  5. Если “01.1.10_1.7_2 Процедура добавления записи в буфер отслеживания локаций, для которых генерируется ответ от ИИ-модели” была выполнена:
    1. Не успешно, на запрос “Generate ai-description” возвращается ошибка “0607”.
    2. Успешно, выполняется добавление сообщения “Локация” в очередь “Создания описания локации для кампании ИИ-моделью OpenAI” с параметрами:
      1. location_id - Идентификатор локации, которая была создана на этапе “3_b” данной процедуры;

06_5_9.1 Ошибки при выполнении проверки 06_5_9

Код ошибки Этап Локаль Текст ошибки
0607 2_b_i en “Description generation is already in progress. Please wait.(code: 0607)”
es “La generación de la descripción ya está en curso. Por favor, espera. (código: 0607)”
pt “A geração da descrição já está em andamento. Por favor, aguarde. (código: 0607)”
de “Die Beschreibungserstellung läuft bereits. Bitte warten. (code: 0607)”