Техническое задание
Техническое задание на разработку интеграции с АСБ «Профкурорт»
1. Общие сведения
1.1. Полные наименования
Полное названия виджета интеграции - Интеграция с АСБ «Профкурорт»
Полное наименование сторонней системы: Aвтоматизированная система бронирования «Профкурорт»
Полное наименование CRM-системы: «amoCRM»
1.2. Сокращенные наименования
Сокращенное условное наименование:
Интеграция с АСБ «Профкурорт: Виджет, Интеграция,
Aвтоматизированный системы бронирования «Профкурорт»: АСБ
Сокращенное условное наименование CRM-системы «amoCRM»: CRM
1.3. Наименование Заказчика и Подрядчик
Добавить данные
1.4. Перечень документов, на основании и с учетом которых создается интеграция
Добавить данные
- Договор №000000 от XX.XX.XX
- Документация к АСБ
- Список полей CRM системы
1.5. Плановые сроки начала и окончания работы по созданию Интеграции
Плановые сроки начала работ: с даты подписания договора и оплаты.
Плановые сроки окончания работ: в соответствии с разделом 5 настоящего Технического задания.
1.6. Сведения об источниках и порядке финансирования работ
Финансирование работ производится за счет средств Заказчика. Оплата производится поэтапно.
1.7. Порядок оформления и предъявления заказчику результатов работ по созданию Интеграции
Приемочные испытания функционирующей интеграции проводятся на серверах Заказчика. Порядок оформления и предъявления Заказчику результатов работ должен соответствовать разделам 5-7 настоящего документа. Документация к API интеграции должна быть передана в электронном виде (Swagger). Текстовые документы должны быть представлены в форматах PDF. Акты сдачи-приемки выполненных работ должны быть предоставлены в электронном виде.
1.8. Список терминов и сокращений
| Сокращение | Описание |
|---|---|
| JWT авторизация | процесс идентификации и проверки (подтверждения) прав пользователя к площадке amoCRM |
| Пользователь | авторизованный пользователь открытой или закрытой части CRM |
| Администратор | роль пользователя, наделенного полными правами доступа к административному интерфейсу CRM |
| Интерфейс | совокупность возможностей, способов и методов взаимодействия пользователей CRM и АСБ для обмена информацией между ними, определённая характеристиками Интеграции |
| Роль пользователя | совокупность прав и ограничений на доступ к определенным функциям CRM |
| API | программный интерфейс приложения для обеспечения взаимодействия с внешними модулями и программами |
2. Назначение и цели создания Интеграции
2.1. Назначение и описание Интеграции
Интеграция предназначена для работы менеджеров в режиме одного окна (CRM) с системой АСБ и синхронизации данных (по статусам) между двумя системими. Взаимодействие с Виджетом будет осуществляться через web-интерфейс внутри amoCRM (в карточке Сделки). Каждый пользователь Интеграции должен быть авторизован в площадке CRM и иметь доступ к необходимым разделам системы.
Для пользователей предусмотрены следующие интерфейсы:
- Список бронирований в АСБ связанных со сделкой
- Поиск свободных категорий номеров и создание бронирования в АСБ
- Редактирования бронирования в АСБ
Интеграция имеет Русский интерфейс и работает только на RU площадках (amocrm.ru) amoCRM. Работа с другими локализациями CRM не предусмотрена.
2.2. Цели создания Интеграции
Целями создания Интеграции являются:
- Упрощения процедур поиска свободных номеров в АСБ;
- Упрощение процедур для создания и редактирования бронирований;
- Связи бронирований в АСБ и сделками(клиентами) в CRM;
- Синхронизация данных между системами и дальнейшая автоматизация;
Выполнение данной работы предусматривает как саму разработку Интеграции, так и обеспечение взаимодействия ее участников, проведение исследовательской и аналитической работы, оказание консультационного и методологического сопровождения разрабатываемой Интеграции, а также сопровождение разработки, запуска и процесса работы Интеграции (техническая поддержка) до срока окончания работ по настоящем Техническому заданию. Исполнитель, выполняя работы по данному Техническому заданию, должен учитывать, что Интеграция предполагает постоянное дальнейшее развитие. Выполненные Исполнителем работы по данному Техническом заданию не должны чинить препятствия дальнейшему развитию Интеграции, в том числе необходимо обеспечивать качество, чистоту и выдержанную стилистику программного кода (отсутствие «хардкода»).
3. Характеристики объекта автоматизации
3.1. Краткие сведения об объекте автоматизации
Объектом автоматизации является совокупность процессов взаимодействия пользователя CRM и интерфейсом АСБ. API Интеграции разворачивается на выделенных серверах, арендованных Заказчиком. JS-виджет хранится на серверах amoCRM.
4. Требования к Интеграции
4.1. Общие требования и возможности
Функциональные возможности Интеграции:
- Отображение в Сделках связанного бронирования в АСБ. Сделка(CRM) и Бронирование(АСБ) сопоставляются 1к1. Связывание происходит по полю Номер заказа в CRM (см Примечание 2). Если поле не заполнено (новая Сделка) - считаем что нет созданных бронирования в АСБ. Отмена бронирования (закрытие сделки) влечет за собой автоматическую отмену брони в АСБ.
- Создание бронирования в АСБ из карточки Сделки. Полностью повторяется интерфейс создания заказа из АСБ, за исключение данных плательщика - они берутся из карточки Контакта. При выполнении бронирования бронирования заполяются все сопоставленные поля (см Примечание 2) в карточки Сделки, меняется статус (см Примечание 3) и добавляется уведомление в примечание. Бронирование осуществляется как по квоте так и Под запрос. В полях (объекты и программы) доступен поиск. Доступно бронирование не более 8 номеров за 1 заказ (из за ограничений на стороне АСБ).
- Редактирование бронирований на стороне Интеграции. При редактировании бронирования из интерфейса Интеграции - данные в АСБ обновляются, сопоставленные поля так же обновляются (см Примечание 3). Статусы синхронизируются (см Примечание 3).
- Восстановление работы при ошибках При возникновении ошибок в процессе создания заказов или синхронизации пользователь уведомляется об этом, задача остается в очереди и повторяется при восстановлении работы Интеграции.
- Обновление полей при изменении на стороне АСБ. Синхронизация данных происходит раз в N минут (за прошедшие N минут). Поиск сделки происходит по полю Номер заказа. Обновляются сопоставленные поля (см Примечание 2) и Статусы (см Примечание 3) сделки. При ошибке во время синхронизация происходит уведомления пользователя, задача остается в очереди и повторяется при восстановлении работы Интеграции. Если заказ не найден в amoCRM - он считается новым (созданным на стороне АСБ), что влечет за собой создание новой сделки в amoCRM. При аннуляции заказа на стороне АСБ - сделка переходит в закрытый статус (Не успешно).
- Счет хранятся на стороне АСБ. В amoCRM доступна ссылка на него в соответствующем поле (см Примечание 2).
- Разграничение прав просмотра объектов бронирования по группам пользователей amoCRM.
Интеграция должна разрабатываться в соответствии со следующими общими требованиями:
- Должна быть реализовано разграничение доступа к формируемой информации для различных пользователей Интеграции (на основании ролей в CRM);
- Должен быть реализован механизм резервного копирования БД с сервера Интеграции;
- Интеграция должна быть открытой к расширению функционала и интеграции другими ресурсами (через API);
- Интеграция должна соблюдать ограничения API amoCRM - 7 запросов/секунду;
- Должен быть реализован механизм очередей;
- Должен быть реализован механизм уведомления об ошибках;
4.1.1. Требования браузеру для работы Интеграции
- Google Chrome не ниже версии 65;
- Mozilla Firefox не ниже версии 40
- Apple Safari не ниже версии 11.
- Включенной поддержка JavaScript в браузере.
4.1.2. Требования в веб-серверу для работы Серверной части
- Операционная система Ubuntu версии не ниже 21.04 LTS
- ЦП не менее 2 ядер (процессорное время не менее 20%)
- Оперативная память не менее 1 гб.
- Место на жестком диске не менее 20 гб.
4.1.2. Требования в API Интеграции
Разработка API должна осуществляться с применением принципов RESTful API. Доступ к API должен осуществляться с помощью защищённого протокола HTTPs. Доступ к методам должен быть ограничен списком IP адресов систем Заказчика и разработчиков дополнительных сервисов. Принимаемые и возвращаемые поля должны быть реализованы в формате JSON.
Минимальный набор данных, получаемых системами Заказчика посредством API Интеграции, должен включать:
- POST-метод авторизации
- GET-метод получения списка бронирований по ID сделки
- POST-метод создания бронирования
- PATCH-метод редактирования бронирования
- GET-метод получения списка обьектов размещения
- GET-метод получения списка программ объектов размещения
- GET-метод получения списка категорий номеров
- GET-метод получения квоты доступных номеров
- GET-метод получения списка категорий номеров
- GET-метод расчета стоимости проживания
Описание методов должно быть доступно в Swagger.
4.2. Сценарии взаимодействия (User Story)
Визуализация интерфейсов доступны в Приложение 1.
Интеграция должны обрабатывать следующие сценарии:
- Создание нового бронирования в АСБ (через интерфейс виджета в карточке Сделки CRM)
flowchart LR
lead(Пользователь открыл\nкарточку сделки)
lead -.-> tab(Перешел во вкладку\nЗаказы АСБ)
tab -.-> create(Кликнул по кнопке\nЗАБРОНИРОВАТЬ НОМЕР)
create -.-> selectObject(Выбрал\nОбьект размещения\n)
selectObject -.-> selectDates(Выбрал\nДаты размещения)
selectDates -.-> selectProgram(Выбрал\nПрограмму пребывания)
selectProgram -.-> selectCategory(Выбрал доступную или под заказ\nКатегорию номера)
selectCategory -.-> selectPersons(Заполнил\nданные гостей)
selectPersons -.-> createOrder(Кликнул по кнопке\nСОЗДАТЬ ЗАКАЗ)- Редактирования бронирования в АСБ (через интерфейс виджета в карточке Сделки CRM)
flowchart LR
lead(Пользователь открыл\nкарточку сделки)
lead -.-> tab(Перешел во вкладку\nЗаказы АСБ)
tab -.-> create(Выбрал\nЗАКАЗ)
create -.-> selectObject(Изменил данные заказа)
selectObject -.-> createOrder(Кликнул по кнопке\nИЗМЕНИТЬ ЗАКАЗ)- Просмотр списка заказов в АСБ (через интерфейс виджета в карточке Сделки CRM)
flowchart LR
lead(Пользователь открыл\nкарточку сделки)
lead -.-> tab(Перешел во вкладку\nЗаказы АСБ)1 сделка в CRM = 1 бронированию в АСБ
4.3. Структура Интеграции
- JS-виджет (фронтенд)
- Серверная часть (сервисы)
4.3.1. Структура и описание JS-виджета
JS-виджет должен обеспечивать возможность отображения списка бронирований, функционала создания и редактирования заказов в АСБ. Подрядчиком должен быть разработан механизм разграничения прав для различных ролей пользователей согластно правам пользователей CRM системы.
Язык программирования - JavaScript
Фреймворк - Vue.
4.3.2. Структура и описание серверной части
Серверная часть должна представлять собой интерфейс взаимодействия между Пользователем (или CRM) и АСБ. Состоит из набора модулей.
| Модуль | Описание |
|---|---|
| ParametersModule | Работа с переменными в БД (key-value) |
| OAuthModule | Авторизацию и идентификацию пользователей Интеграции и CRM |
| QueueModule | Работу очередей (RabbitMQ) |
| AmoCrmApiModule | API amoCRM |
| AsbApiModule | API АСБ |
| OrderModule | Работа с заказами (список, создание, изменение) |
| SyncModule | Синхронизация заказов между системами |
| LoggerModule | Логирование ошибок |
| NotificationModule | Нотификация пользователей |
Язык программирования - TypeScript (NodeJS)
Фреймворк - NestJS.
БД - MongoDB
4.3.2.1 Структура и описание ParametersModule
flowchart
subgraph ParametersModule
subgraph ParametersService
getParamByName(getParamByName)
updateParamByName(updateParamByName)
captureException(captureException)
end
end Модуль необходим для работы с изменяемыми переменными в Интеграции, хранимыми в БД.
| Переменная | Тип | Описание |
|---|---|---|
CRM_TOKEN_EXPIRED_AT |
Date | Дата истечения токена авторизации в CRM |
CRM_ACCESS_TOKEN |
String | Access Token CRM |
CRM_REFRESH_TOKEN |
String | Refresh Token CRM |
LAST_SYNC_DATE |
Date | Дата и время последней успешной синхронизации |
| Метод | Описание |
|---|---|
getParamByName |
Получение параметра по ключу |
updateParamByName |
Обновление параметра по ключу |
captureException |
Обработка ошибок |
4.3.2.2 Структура и описание OAuthModule
flowchart
subgraph OAuthModule
subgraph OAuthService
auth(auth)
refreshTokens(refreshTokens)
checkAuth(checkAuth)
captureException(captureException)
end
end Модуль необходим для авторизации в CRM.
| Метод | Описание |
|---|---|
auth |
Авторизация по ключу |
refreshTokens |
Обновление токенов |
checkAuth |
Проверка времени жизни токенов |
captureException |
Обработка ошибок |
4.3.2.3 Структура и описание OAuthModule
flowchart
subgraph QueueModule
subgraph QueueService
onModuleInit(onModuleInit)
publish(publish)
subscribe(subscribe)
captureException(captureException)
end
end Модуль необходим для работы с сервисом очередей RabbitMQ
| Метод | Описание |
|---|---|
onModuleInit |
Подключение к серверу очередей |
publish |
Создание новой задачи |
subscribe |
Подписка на очередь |
captureException |
Обработка ошибок |
4.3.2.4 Структура и описание AmoCrmApiModule
flowchart
subgraph AmoCrmApiModule
subgraph AmoCrmApiService
getLeadByID(getLeadByID)
createLead(createLead)
updateLead(updateLead)
getContactByID(getContactByID)
createContact(createContact)
updateContact(updateContact)
captureException(captureException)
end
end Модуль необходим для работы с API amoCRM
| Метод | Описание |
|---|---|
getLeadByID |
Получение сделки по ID |
createLead |
Создание сделки |
updateLead |
Изменение сделки |
getContactByID |
Получение контакта по ID |
createContact |
Создание контакта |
updateContact |
Изменение контакта |
captureException |
Обработка ошибок |
4.3.2.5 Структура и описание AsbApiModule
Модуль необходим для работы с API АСБ Профкурорт. Необходимо реализовать все методы доступные в API (см Приложение 2)
4.3.2.6 Структура и описание OrderModule
flowchart
subgraph OrderModule
subgraph OrderController
create(create)
list(list)
update(update)
end
subgraph OrderService
createLetter(createLetter)
lettersListByLeadId(lettersListByLeadId)
updateLetter(updateLetter)
captureException(captureException)
end
end Модуль необходим для работы с фронтендом интеграции. Содержит контроллер API.
| Метод | Описание |
|---|---|
createLetter |
Создание бронирования в АСБ |
lettersListByLeadId |
Получение списка бронирований |
updateLetter |
Изменение бронирования |
captureException |
Обработка ошибок |
4.3.2.7 Структура и описание SyncModule
flowchart
subgraph SyncModule
subgraph SyncController
hook(hook)
end
subgraph SyncService
subscrube(subscrube)
cron(cron)
process(process)
processHook(processHook)
captureException(captureException)
end
end Модуль необходим для работы с фронтендом интеграции. Содержит контроллер API. Данные синхронизируются в обе стороны. Сопоставляются поля сделки, контакта и статусы. При закрытии сделки на стороне CRM заказ так же должен аннулироваться в АСБ.
| Метод | Описание |
|---|---|
subscrube |
Подписка на очередь событий |
cron |
Создание задачи на обновление (раз в N минут) |
process |
Синхронизация данных (АСБ -> CRM) |
process |
Синхронизация данных (CRM -> АСБ) |
captureException |
Обработка ошибок |
4.3.2.8 Структура и описание LoggerModule
Модуль необходим для логирования запросов и ошибок в работе интеграции. Логирование происходит в формате JSON.
4.3.2.9 Структура и описание NotificationModule
flowchart
subgraph NotificationModule
subgraph NotificationService
push(push)
email(email)
captureException(captureException)
end
end Модуль необходим для уведомления пользователей об событиях и ошибках в работе Интеграции.
| Метод | Описание |
|---|---|
push |
Push-уведомление в CRM |
email |
Email-уведомление |
captureException |
Обработка ошибок |
5. Порядок контроля и приемки Интеграции
5.1. Виды, состав, объем и методы испытаний системы и ее составных частей
Должны быть проведены следующие виды тестов:
- Unit-тестирование;
- Функциональные тесты;
5.2. Общие требования к приемке работ по стадиям
Приемка результатов работ осуществляется поэтапно в соответствии с календарным планом выполнения работ по договору.
Приемка результатов выполнения работ по этапам оформляется Актом сдачи работ.
5.3. Сведения о гарантийном обслуживании Интеграции
Гарантийное обслуживание проводится в сроки, определенные договором. Подрядчик должен гарантировать, что созданная Интеграция будет функционировать в соответствии со своим назначением не менее 1 года с даты подписания договора при условии невмешательства в исходный код и отсутствия изменений на стороне информационных систем (АСБ и/или CRM), с которыми организовано взаимодействие. При этом возможны незначительные отклонения его технических и потребительских характеристик, а также отдельные ошибки, не создающие препятствий для получения положительных результатов от эксплуатации системы.
Подрядчик не гарантирует отсутствие недостатков или сбоев в процессе работы, возникающих по причине несоответствия оборудования или установленного на рабочем месте программного обеспечения конечного пользователя требованиям, предъявляемым к характеристикам клиентских мест (см. пункт «Требования браузеру для работы Интеграции»).
6. Требования к развертыванию Интеграции
6.1. Развертывание и конфигурирование
Система должна быть реализована и развернута на серверном оборудовании, арендованном Заказчиком. В случае необходимости Подрядчиком должны быть установлены обновления, если эти обновления не включены в состав дистрибутива.
Приложение 1. Мокапы интерфейсов интеграции
1. Список заказов.
2. Выбор номеров по датам.
3. Редактор гостей.
Приложение 2. Сопоставление полей CRM и АСБ
| Поле amoCRM | Поле АСБ | Описание и применение |
|---|---|---|
| Сделка -> Бюджет | Сумма | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Дата заезда | Дата заезда | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Дата отъезда | Дата отъезда | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Количество суток | Рассчитывается автоматически | |
| Сделка -> Санаторий | Объект размещения | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Категория номера | Категория номера | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Программа лечения | Программа пребывания | Для дальнейшего уведомление клиента и формирования документов |
| Сделка -> Количество взрослых | Рассчитывается автоматически | |
| Сделка -> Количество детей | Рассчитывается автоматически | |
| Сделка -> Возраст детей | Рассчитывается автоматически | |
| Сделка -> Номер заказа | ID | Для синхронизации данных (не редактируемое) |
| Сделка -> Скидка | Для дальнейшего уведомление клиента и формирования документов | |
| Сделка -> ФИО всех гостей | Заполняется на основе массива гостей (через запятую) | |
| Сделка -> Даты рождения | Заполняется на основе массива гостей (через запятую) | |
| Сделка -> Ссылка на счет | Счет | Для дальнейшего уведомление клиента, документооборота |
| Контакт -> Имя контакта | ФИО плательщика | Для дальнейшего уведомление клиента и формирования документов |
| Контакт -> Email | Email плательщика | Для дальнейшего уведомление клиента и формирования документов |
| Контакт -> Дата рождения | Дата рождения плательщика | Для дальнейшего уведомление клиента и формирования документов |
| Контакт -> Телефон | Телефон плательщика | Для дальнейшего уведомление клиента и формирования документов |
Приложение 3. Сопоставление статусов CRM и АСБ
| amoCRM | АСБ |
|---|---|
| - | Запрос |
| - | Забронирован |
| - | Продан |
| - | Оплачен |
| - | Аннулирован |
Приложение 4. Документация к API АСБ
Основное:
/**
* Переменные
**/
const BASE_PATH = 'http://test.ihmanagement.ru';1. Авторизация и лимиты
Аутентификация Digest - логин-пароль пользователя пересылаются через сеть в зашифрованом виде по алгоритму MD5
2. Обьекты размещения:
| METHOD | URL | Описание | Параметры |
200 Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/objects | Получение списка доступных объектов размещения | - | Objects[] |
POST |
/webservice/api/res/v1/objects | Получение списка доступных объектов размещения | - | Objects[] |
interface Object {
// Уникальный код объекта в АСБ. Если не указан, выдаются все программы для заданного пользователя (формат?)
objid?: any;
// Название объекта размещания
objnam?: string;
// Расчетный час
payhour?: string;
// Список id групп объектов (разделитель ",")
grpid_delim?: string;
// Путь до картинки
img_link?: string;
// Описание обьекта
objnot?: string;
// Адрес обьекта
objaddr?: any;
// (формат?)
latitude?: any;
// Долгота (формат?)
longitude?: any;
// Возраст до которого гость счатется ребенком
child_age?: number;
// Объект геолокации (формат?)
geoobject?: any;
// Время заезда (формат?)
hourin?: any;
// Время выезда
hourout?: время выезда
// Звездность объекта (0 - не задано)
objstars?: number;
// Код типа объекта см endpoint objtyps
objtypid?: number;
}3. Программы размещения:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/programms | Получение списка программ объектов размещения | GetProgrammsParams |
Programm[] |
POST |
/webservice/api/res/v1/programms | Получение списка программ объектов размещения | GetProgrammsParams |
Programm[] |
interface GetProgrammsParams {
// Код объекта размещения (формат?)
objid?: any;
}
interface Programm {
// Код программы (формат?)
pricelistid?: any;
// progid = pricelistid код программы (формат?)
progid?: any;
// Название
prognam?: string;
// Примечание
prognot?: string;
// Код объекта размещения (формат?)
objid?: any;
// Код договора (формат?)
concod?: any;
// Максимально разрешенное кол-во суток в заказе
maxlength?: number;
// Минимально разрешенное кол-во суток в заказе
minlength?: number;
// Дата начала действия программы
datein?: Date;
// Дата окончания действия программы
dateout?: Date;
// Пары дат ограничения действия программы (формат?)
jsonrestriction?: any;
// Кол-во суток от текущей даты с которых начинает работать программа
quotestartdays?: number;
// Массив кодов услуг доступных при бронировании по данной программе
servcods?: any[];
}4. Категории номеров
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/categs | Получение списка категорий номеров | GetCategoriesParams |
Category[] |
POST |
/webservice/api/res/v1/categs | Получение списка категорий номеров | GetCategoriesParams |
Category[] |
interface GetCategoriesParams {
// Код объекта размещения (формат?)
objid?: any;
}
interface Category {
// Код категории (формат?)
catcod?: any;
// Возможность размещения 1 гостя во весь номер 1-возможно/0-не возможно
oneplacefl?: number;
// Название
catnam?: string;
// Сокращенное название
catlab?: string;
// Кол-во основных мест
catbednum?: number;
// Кол-во доп мест
catdopnum?: number;
// Примечание
catnot?: string;
// Кол-во картинок в массиве catgalery
imgcount?: number;
// Галерея картинок
catgalery?: CategoryGallery[];
// Массив кодов свойств, описание см интерфейс catprops
catpropids?: any[];
}
interface CategoryGallery {
// Ссылка на файл
href?: string;
// Заголовок
title? string;
}5. Свойства категорий:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/programms | Получение списка свойств номеров | - | CategoryProperty[] |
POST |
/webservice/api/res/v1/programms | Получение списка свойств номеров | - | CategoryProperty[] |
type CategoryProperty {
// Код свойства (формат?)
catpropid?: any;
// Название
catpropnam?: string;
}6. Список цен по категориям:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/websrvice/api/res/v1/prices | Список цен номеров | GetPricesDto |
Price[] |
POST |
/websrvice/api/res/v1/prices | Список цен номеров | GetPricesDto |
Price[] |
interface GetPricesDto {
// уникальный код объекта в АСБ. Если не указан, выдаются все программы (формат?)
objid?: any;
// кол-во дней на которые запрашиваются цены (например =60 - тогда цены будут выданы на 60 дней вперед)
length?: number;
}
interface Price {
// Дата прейскуранта
datein?: Date;
// Код категории (формат?)
catcod?: any;
// Cтоимость номера целиком
price?: number;
// Cтоимость места
priceplace?: number;
// Cтоимость доп места
pricedop?: number;
// Cтоимость детского места
pricechild?: number;
// Cтоимость детского доп места
pricedopchild?: number;
// Код валюты (формат?)
curintcod?: any;
// Код цены (формат?)
pricelistid?: any;
// progid = pricelistid код цены (формат?)
progid?: any;
// Код услуги (формат?)
servcod?: any;
}7. Квоты:
| METHOD | URL | Описание | Параметры | Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/quotes | Получение квоты доступных номеров | GetQuotesParams |
Quote[] |
POST |
/webservice/api/res/v1/quotes | Получение квоты доступных номеров | GetQuotesParams |
Quote[] |
interface GetQuotesParams {
// уникальный код объекта в АСБ. Если не указан, выдаются все (формат?)
objid?: any;
// дата с которой выдать квоту. Фомат YYYY-MM-DD. По умолчанию: текущая дата
datein?: Date;
// кол-во дней на которые запрашиваются квоту (например =60 - тогда квота будет выдана на 60 дней вперед datein). По умолчанию: 7
length?: number;
// код категории номера, если не указан то все доступные на объекте (формат?)
catcod?: any;
}
interface Quote {
// Дата ?
resdate?: Date;
// Код категории (формат?)
catcod?: any;
// Кол-во номеров для бронирования
quoteval?: number;
// Кол-во номеров всего (если "0" - значение не задано)
fondval?: number;
// Код объекта размещения (формат?)
objid?: any;
// Код договора с объектом (формат?)
concod?: any;
// № договора с объектом (формат?)
connr?: any;
}8. Заказы:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/letters | Поиск заказа | GetLetterParams |
CreatedLetter[] |
POST |
/webservice/api/res/v1/letters | Регистрация заказа | LetterJson |
SetLetterResult |
POST |
/webservice/api/res/v1/setletter | Регистрация заказа | LetterJson |
SetLetterResult |
PUT |
/webservice/api/res/v1/letters | Изменение заказа | LetterJson |
UpdateLetterResult |
DELETE |
/webservice/api/res/v1/letters | Аннуляция заказа | LetterJson |
DeleteLetterResult |
/**
* Параметры запроса (получение заказов)
**/
interface GetLetterParams {
// Регистрационный № заказа в АСБ (формат?)
letregnr?: any;
// Уникальный (числовой) код заказа в АСБ
letcod?: number;
// если задан 1 то выдает только оплаченные заказы
payed_letters?: number;
// дата начала диапазона. Формат даты yyyy-mm-dd
datein?: string;
// дата конца диапазона. Формат даты yyyy-mm-dd
dateout?: string;
}
/**
* Заказ (получение)
**/
interface CreatedLetter {
// Код заказа в АСБ (формат?)
letcod?: any;
// регистрационный № заказа в АСБ (формат?)
letregnr?: any;
// Примечание к заказу
letnot?: string;
// Название статуса
letstnam?: string;
// Код статуса (формат?)
letstcod?: any;
// ФИО плательщика
payer_fio?: string;
// Телефон плательщика
payer_phone?: string;
// Email
payer_mail?: string;
// Дата заезда ??? формат
datein?: string;
// Дата выезда ??? формат
dateout?: string;
// Дата регистрации заказа в АСБ
datereg?: Date;
// Cтоимость
price?: number;
// расчетная сумма предоплаты
prepay?: number;
// Числовой код валюты ISO
curintcod?: number;
// Буквенный код валюты ISO
curintlab?: string;
// № дисконтной карты (формат?)
discardnr?: any;
// % скидки по дисконтной карте
discardprc?: number;
// Код агента АСБ (формат?)
agentcod?: any;
// Уникальный идентификатор плательщика
payer_id?: any;
// Наименование агента продавшего заказ
agentnam?: string;
// Код объекта размещения (формат?)
objid?: any;
// Название объекта размещения
objnam?: string;
// Дата перевода в статус 1 (Забронирован)
letstdate1?: Date;
// Дата перевода в статус 2 (Продан)
letstdate2?: Date;
// Дата перевода в статус 3 (Оплачен)
letstdate3?: Date;
// Дата перевода в статус 4 (Аннулирован)
letstdate4?: Date;
// Примечание по заказу
letnot?: string;
}
/**
* Заказ (создание и обновление)
**/
interface LetterJson {
js_data: Letter;
}
interface Letter {
// Код заказа в АСБ тип BigInt при регистрации заказа ставить 0
letcod: number = 0;
// Дата заезда (yyyy-mm-dd)
datein: string;
// Дата выезда (yyyy-mm-dd)
datein: string;
// Код программы
pricelistid: any;
// Примечание к заказу
letnot: string;
// Признак запроса
queryfl: QueryFlCode;
// Номера
rooms: Room[];
// Стоимость
price: number;
// № дисконтной карты, если нет - пусто
discardnr: string;
// Статус
letstatus: LetterStatus;
// Агент
agent: LetterAgent;
// ???
contract: LetterContract;
// ???
addservices: LetterAddService;
// Плательщик
payer: LetterPayer;
}
/**
* Статус
**/
interface LetterStatus {
// Код статуса
letstcod: number;
// Название статуса
letstlab: string;
// Дата перехода в статус
letstdate: Date;
}
/**
* Агент
**/
interface LetterAgent {
// Код агента
agentcod: number;
// Название агента
agentnam: string;
}
/**
* Договор
**/
interface LetterContract {
// Код
concod: number;
// Название
connr: string;
}
/**
* Дополнительный сервис
**/
interface LetterAddService {
// Код
servcod: number;
// Название
servnam: string;
// Стоимость
servsum: number;
}
/**
* Плательщик
**/
interface LetterPayer {
// Фамилия
lastname: string;
// Имя
firstname: string;
// Отчество
middlename: string;
// Email
email: string;
// Телефон
cellphone: string;
// Дисконтная карта
disCard: string;
}
/**
* Номер
**/
interface Room {
// Код категории
catcod: string;
// ???
catplacefl: number;
// Массив клиентов
clients: Client[];
}
/**
* Клиент
**/
interface Client {
// ID клиента
clientid?: number;
// Код программы
pricelistid?: string;
// Фамилия
clinam1: string;
// Имя
clinam2: string;
// Отчество
clinam3: string;
// Примечание
clinot: string;
// Дата рождения (yyyy-mm-dd)
datebirthday: string;
// Скидка
discount: number;
// Процент агентской скидки
disprc: string;
// Признак дополнительного места
dopplacefl: DopPlaceFlag
// Активность гостя
enablefl: boolean;
// Код страны по ISO (РФ - 643)
countintcod: number;
// Услуги по лечению
heal: ServiceItem[];
// Услуги по питанию
mealType: ServiceItem[];
// Стоимость
price: number;
// Код пола клиента
sexcod: ClientSexCode;
// Код возраста
agecod: ClientAgeCode;
}
/**
* Услуга
**/
interface ServiceItem {
// Код услуги
servcod: string;
// Название
servnam: string;
// Цена
servprice: number;
}
interface UpdateLetterResult {
ref: number;
mes: string;
}
interface DeleteLetterResult {
ref: number;
mes: string;
}
interface SetLetterResult {
// Регистрационный № заказа
mes: any;
// код договора
concod: any;
// код валюты ISO
curintcod: number;
// наименование валюты ISO
curintlab: string;
// url для оплаты (при наличии платежной системы)
paysysurl?: string;
// код платежной системы
paysysid: string;
// признак статуса запрос (0 - заказ, 1- запрос)
queryfl: QueryFlCode
}
enum QueryFlCode {
BOOKING = 0,
REQUEST = 1
}
enum DopPlaceFlag {
MAIN = 0,
ADDITIONAL = 1
}
enum ClientSexCode {
MAN = 1,
WOMEN = 2
}
enum ClientAgeCode {
ADULT = 1,
CHILDREN = 2
}9. Расчет стоимости:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
POST |
/webservice/api/res/v1/calcsum | Рассчет стоимости | LetterJson |
LetterJson |
Типизация совпадает с п.6
10. Услуги:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/services | Получение списка доступных услуг по объектам размещения | GetServicesParams |
GetServicesResponse |
POST |
/webservice/api/res/v1/services | Получение списка доступных услуг по объектам размещения | GetServicesParams |
- |
interface GetServicesParams {
// уникальный код объекта в АСБ
objid: any;
}
/**
* Ответы сервера
* [200]
**/
interface GetServicesResponse {
// Код услуги
ervcod: any;
// Код объекта
objid: any;
// Название услуги
servnam: string;
// описание услуги
servnot: string;
// название группы услуги
servgrpnam: string;
// код группы услуги
servgrpid: any;
// тип услуги
servtypid: any;
// описание типа услуги
servtypnam: string;
}9. Типы объектов:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
GET |
/webservice/api/res/v1/objtyps | Получение списка доступных типов для объектов размещения | - | GetObjectTypesResponse |
POST |
/webservice/api/res/v1/objtyps | Получение списка доступных типов для объектов размещения | - | GetObjectTypesResponse |
/**
* Ответы сервера
* [200]
**/
interface GetObjectTypesResponse {
// Код типа объекта размещения
objtypid: any;
// Название типа объекта размещения
objtypnam: string;
}11. Смена статуса:
| METHOD | URL | Описание | Параметры | [2xx] Результат |
|---|---|---|---|---|
POST |
/webservice/api/res/v1/letter_set_status_sold | Изменение статуса заказа с "Забронирован" на "Продан" | SetLetterSoldStatusParams |
SetLetterSoldStatusResponse |
interface SetLetterSoldStatusParams {
// Код заказа
letcod: any;
}
/**
* Ответы сервера
* [200]
**/
interface SetLetterSoldStatusResponse {
// 1 - Успешно, (-2) - нет вкоты, (-3) - нет денег на счете агента
ref: ResponseStatus;
// Описание
mes: string;
}
enum ResponseStatus {
OK = 1,
NOT_ROOMS = -2,
NOT_MONEY = -3
}