====== ProBonus API: Рассылки, отзывы и Wallet ======

Отправка сообщений гостям, загрузка файлов, работа с отзывами, баланс и транзакции для карт Wallet.

Общие правила (адрес, авторизация, форматы, коды ошибок) — на странице [[external:pro_bonus:10_probonus_api:20_reference|ProBonus API. Справочник методов]].

===== Список методов =====

^ Метод ^ Адрес ^ Назначение ^
| ''POST'' | ''/api/v0/mailing/add_separate_message'' | [[#отправка_отдельного_сообщения_гостю|Отправка отдельного сообщения гостю]] |
| ''POST'' | ''/api/v0/mailing/cancel'' | [[#отмена_рассылки|Отмена рассылки]] |
| ''GET'' | ''/api/v0/mailing/config'' | [[#доступные_каналы_рассылки|Доступные каналы рассылки]] |
| ''POST'' | ''/api/v0/media/upload_files'' | [[#загрузка_файлов_изображений|Загрузка файлов (изображений)]] |
| ''POST'' | ''/api/v0/reviews/add_answer'' | [[#ответ_на_отзыв|Ответ на отзыв]] |
| ''POST'' | ''/api/v0/reviews/add_message'' | [[#добавление_сообщения_гостя_в_отзыв|Добавление сообщения гостя в отзыв]] |
| ''POST'' | ''/api/v0/reviews/close'' | [[#закрытие_отзыва|Закрытие отзыва]] |
| ''GET'' | ''/api/v0/reviews/get_all_in_process_by_account_id'' | [[#незавершённые_отзывы_гостя|Незавершённые отзывы гостя]] |
| ''GET'' | ''/api/v0/reviews/get_all_in_process_opened_minutes_ago'' | [[#незавершённые_отзывы_открытые_n_минут_назад|Незавершённые отзывы, открытые N минут назад]] |
| ''GET'' | ''/api/v0/reviews/get_by_id_extended'' | [[#чтение_отзыва_по_id_расширенно|Чтение отзыва по id (расширенно)]] |
| ''POST'' | ''/api/v0/reviews/insert'' | [[#создание_отзыва|Создание отзыва]] |
| ''GET'' | ''/api/v0/reviews/list'' | [[#список_отзывов|Список отзывов]] |
| ''POST'' | ''/api/v0/reviews/mark_processed'' | [[#отметка_отзыва_как_обработанного|Отметка отзыва как обработанного]] |
| ''GET'' | ''/api/v0/wallet/get_balance'' | [[#баланс_для_карты_wallet|Баланс для карты Wallet]] |
| ''GET'' | ''/api/v0/wallet/get_transactions'' | [[#транзакции_для_карты_wallet|Транзакции для карты Wallet]] |
| ''POST'' | ''/api/v0/wallet/request_invoice'' | [[#запрос_счёта_на_оплату_wallet|Запрос счёта на оплату Wallet]] |

===== Рассылки =====

==== Отправка отдельного сообщения гостю ====
**''POST /api/v0/mailing/add_separate_message''**\\
Авторизация: требуется

**Тело запроса** — объект ''AddSeparateMessageDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accountId'' | integer | да | Идентификатор счёта |
| ''channels'' | массив [[#mailingchanneltype|MailingChannelType]] | да | Каналы рассылки |
| ''text'' | string |  | Текст |
| ''media'' | массив string |  | Файлы (изображения) |
| ''subject'' | string |  | Тема |
| ''reviewId'' | integer |  | Идентификатор отзыва |

**Ответ 202:** без содержимого.

==== Отмена рассылки ====
**''POST /api/v0/mailing/cancel''**\\
Авторизация: требуется

**Тело запроса** — объект ''IdDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |

**Ответ 202:** без содержимого.

==== Доступные каналы рассылки ====
**''GET /api/v0/mailing/config''**\\
Авторизация: требуется

**Ответ 200** — объект ''MailingChannelsConfigDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''externalSystemEnabled'' | boolean | да |  |
| ''emailEnabled'' | boolean | да |  |
| ''telegramEnabled'' | boolean | да |  |
| ''walletEnabled'' | boolean | да |  |
| ''maxEnabled'' | boolean | да |  |

===== Файлы =====

==== Загрузка файлов (изображений) ====
**''POST /api/v0/media/upload_files''**\\
Авторизация: требуется

**Тело запроса** (''multipart/form-data'') — объект ''Body_upload_files_api_v0_media_upload_files_post'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''files'' | массив файл | да | Файлы |

**Ответ 200:** JSON (структура в схеме не описана).

===== Отзывы =====

==== Ответ на отзыв ====
**''POST /api/v0/reviews/add_answer''**\\
Авторизация: требуется

**Тело запроса** — объект ''ReviewAddAnswerDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''text'' | string |  | Текст |
| ''reviewId'' | integer | да | Идентификатор отзыва |
| ''accountId'' | integer | да | Идентификатор счёта |

**Ответ 202:** без содержимого.

==== Добавление сообщения гостя в отзыв ====
**''POST /api/v0/reviews/add_message''**\\
Авторизация: требуется

**Тело запроса** — объект ''ReviewMessageInsertDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''text'' | string |  | Текст |
| ''reviewId'' | integer | да | Отзыв |
| ''media'' | string |  | Файлы (изображения) |

**Ответ 200** — объект ''ReviewMessageGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''text'' | string |  | Текст |
| ''reviewId'' | integer | да | Отзыв |
| ''datetime'' | datetime | да | Дата и время |
| ''mediaId'' | integer |  | Приложенный файл |

==== Закрытие отзыва ====
**''POST /api/v0/reviews/close''**\\
Авторизация: требуется

**Тело запроса** — объект ''IdDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |

**Ответ 200** — объект ''ReviewGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор отзыва |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус отзыва |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |

==== Незавершённые отзывы гостя ====
**''GET /api/v0/reviews/get_all_in_process_by_account_id''**\\
Авторизация: требуется

**Параметры запроса:**

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''account_id'' | строка запроса | integer | да | Идентификатор счёта |

**Ответ 200** — массив объектов ''ReviewGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор отзыва |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус отзыва |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |

==== Незавершённые отзывы, открытые N минут назад ====
**''GET /api/v0/reviews/get_all_in_process_opened_minutes_ago''**\\
Авторизация: требуется

**Параметры запроса:**

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''minutes'' | строка запроса | integer | да | Количество минут |

**Ответ 200** — массив объектов ''ReviewWithAdditionalContactInfoGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Идентификатор счёта |
| ''source'' | string |  | Источник |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Идентификатор ресторана |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |
| ''additionalContact'' | [[#additionalcontactgetdto|AdditionalContactGetDto]] |  | Контакт мессенджера |

==== Чтение отзыва по id (расширенно) ====
**''GET /api/v0/reviews/get_by_id_extended''**\\
Авторизация: требуется

**Параметры запроса:**

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | строка запроса | integer | да | Идентификатор объекта |

**Ответ 200** — объект ''ReviewExtendedGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор отзыва |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус отзыва |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |
| ''account'' | [[#reviewaccountbaseinfo|ReviewAccountBaseInfo]] | да | Счёт |
| ''restaurant'' | [[#reviewrestaurantbaseinfo|ReviewRestaurantBaseInfo]] |  |  |
| ''responseCreators'' | string |  |  |
| ''additionalContactType'' | integer |  | Тип контакта мессенджера |
| ''messages'' | массив [[#reviewextendedmessagesitemdto|ReviewExtendedMessagesItemDto]] | да | Сообщения |

==== Создание отзыва ====
**''POST /api/v0/reviews/insert''**\\
Авторизация: требуется

**Тело запроса** — объект ''ReviewInsertDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |

**Ответ 200** — объект ''ReviewGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор отзыва |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус отзыва |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |

==== Список отзывов ====
**''GET /api/v0/reviews/list''**\\
Авторизация: требуется

**Параметры запроса:**

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''date_begin'' | строка запроса | date | да | Начало периода |
| ''date_end'' | строка запроса | date | да | Конец периода |
| ''max_grade'' | строка запроса | integer |  | Максимальная оценка; по умолчанию ''5'' |
| ''restaurant_ids'' | строка запроса | массив integer |  | Фильтр по ресторанам (несколько значений) |
| ''restaurant_other'' | строка запроса | boolean |  | Учитывать операции без ресторана (ручные, внешние); по умолчанию ''false'' |

**Ответ 200** — массив объектов ''ReviewWithAccountInfoGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Идентификатор счёта |
| ''source'' | string |  | Источник |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Идентификатор ресторана |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |
| ''account'' | [[#reviewaccountbaseinfo|ReviewAccountBaseInfo]] | да | Счёт |
| ''restaurant'' | [[#reviewrestaurantbaseinfo|ReviewRestaurantBaseInfo]] |  |  |
| ''responseCreators'' | string |  |  |
| ''additionalContactType'' | integer |  | Тип контакта мессенджера |

==== Отметка отзыва как обработанного ====
**''POST /api/v0/reviews/mark_processed''**\\
Авторизация: требуется

**Тело запроса** — объект ''IdDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |

**Ответ 200** — объект ''ReviewGetDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор отзыва |
| ''grade'' | integer | да | Оценка; мин. 1; макс. 5 |
| ''accountId'' | integer | да | Счёт гостя |
| ''source'' | string |  | Источник отзыва |
| ''additionalContactId'' | integer |  | Контакт мессенджера, через который получен отзыв |
| ''restaurantId'' | integer |  | Ресторан |
| ''status'' | [[#reviewstatus|ReviewStatus]] | да | Статус отзыва |
| ''beginDatetime'' | datetime | да | Начало диалога |
| ''endDatetime'' | datetime |  | Завершение диалога |

===== Wallet =====

==== Баланс для карты Wallet ====
**''GET /api/v0/wallet/get_balance''**\\
Авторизация: требуется

**Ответ 200** — объект ''WalletBalance'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accountBalance'' | number | да | Баланс счёта, руб. |
| ''averageCost'' | number | да |  |
| ''forecast'' | integer | да |  |

==== Транзакции для карты Wallet ====
**''GET /api/v0/wallet/get_transactions''**\\
Авторизация: требуется

**Параметры запроса:**

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''date_from'' | строка запроса | date | да | Начало периода |
| ''date_to'' | строка запроса | date | да | Конец периода |

**Ответ 200** — массив объектов ''WalletTransactionDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''dateTime'' | datetime | да | Дата и время |
| ''sum'' | number |  | Сумма, руб. |
| ''text'' | string | да | Текст |
| ''user'' | string | да | Пользователь |

==== Запрос счёта на оплату Wallet ====
**''POST /api/v0/wallet/request_invoice''**\\
Авторизация: требуется

**Тело запроса** — объект ''RequestInvoiceDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''sum'' | integer | да | Сумма; мин. 1000 |
| ''tin'' | string | да | ИНН |
| ''email'' | string (e-mail) | да | Адрес e-mail |
| ''fullName'' | string |  | ФИО гостя |
| ''phone'' | string |  | Номер телефона |

**Ответ 204:** без содержимого.

===== Модели данных =====

Вложенные объекты и перечисления, на которые ссылаются методы этого раздела.

==== AdditionalContactGetDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор контакта |
| ''type'' | [[#additionalcontacttype|AdditionalContactType]] | да | Тип контакта (канал мессенджера) |
| ''value'' | string | да | Значение (идентификатор чата/пользователя в мессенджере) |
| ''accountId'' | integer | да | Счёт гостя |

==== AdditionalContactType ====
Перечисление (integer). Значения: ''1'', ''2''.

==== MailingChannelType ====
Перечисление (integer). Значения: ''0'', ''1'', ''2'', ''3'', ''4''.

==== ReviewAccountBaseInfo ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''firstName'' | string |  | Имя |
| ''lastName'' | string |  | Фамилия |
| ''middleName'' | string |  | Отчество |

==== ReviewExtendedMessagesItemDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''type'' | [[#reviewmessagetype|ReviewMessageType]] | да | Тип |
| ''datetime'' | datetime | да | Дата и время |
| ''text'' | string |  | Текст |
| ''mediaId'' | integer |  | Идентификатор файла |
| ''media'' | string |  | Файлы (изображения) |
| ''responseCreator'' | string |  |  |
| ''responseCreatorType'' | integer |  |  |

==== ReviewMessageType ====
Перечисление (integer). Значения: ''1'', ''2''.

==== ReviewRestaurantBaseInfo ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string | да | Наименование |

==== ReviewStatus ====
Перечисление (integer). Значения: ''1'', ''2'', ''3''.