====== ProBonus API: Внешние продажи, импорт и инфокиоск ======

Регистрация продаж из внешних систем (не r_keeper), импорт счетов и потрат, страницы инфокиоска.

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

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

^ Метод ^ Адрес ^ Назначение ^
| ''POST'' | ''/api/v0/external/register_check'' | [[#регистрация_внешней_продажи|Регистрация внешней продажи]] |
| ''POST'' | ''/api/v0/external/return_check'' | [[#отмена_внешней_продажи|Отмена внешней продажи]] |
| ''POST'' | ''/api/v0/import_data/import_parsed_rk_pds_row'' | [[#импорт_в_группу_счетов|Импорт в группу счетов]] |
| ''POST'' | ''/api/v0/import_data/import_parsed_spending'' | [[#импорт_распарсенных_потрат_в_бд|Импорт распарсенных потрат в БД]] |
| ''POST'' | ''/api/v0/import_data/import_previous_telegram_bot_db'' | [[#импорт_базы_предыдущей_версии_telegram-бота|Импорт базы предыдущей версии Telegram-бота]] |
| ''GET'' | ''/api/v0/import_data/import_task_status'' | [[#проверка_статуса_задачи_импорта_по_task_id|Проверка статуса задачи импорта по task_id]] |
| ''POST'' | ''/api/v0/import_data/parse_rk_pds_csv'' | [[#загрузка_импорт_счетов_из_файла_обмена_csv|Загрузка (импорт) счетов из файла обмена (CSV)]] |
| ''POST'' | ''/api/v0/import_data/parse_spending_csv'' | [[#парсинг_csv_файла_с_потратами_идентификатор_сумма|Парсинг CSV файла с потратами (идентификатор, сумма)]] |
| ''GET'' | ''/screen/client/get/'' | [[#страница_инфокиоска_ввод_карты|Страница инфокиоска (ввод карты)]] |
| ''POST'' | ''/screen/client/get/'' | [[#поиск_гостя_на_инфокиоске|Поиск гостя на инфокиоске]] |

===== Внешние продажи =====

==== Регистрация внешней продажи ====
**''POST /api/v0/external/register_check''**\\
Авторизация: требуется

Используется для начисления и списания бонусов по чекам внешних систем (не r_keeper): сайт, доставка, другая кассовая система.

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''restCode'' | string | да | Код ресторана (9 цифр) |
| ''checkGuid'' | uuid | да | Уникальный GUID чека во внешней системе; по нему выполняется отмена продажи |
| ''accountId'' | integer | да | Идентификатор счёта |
| ''rkUnit'' | integer |  | Номер кассы (станции) во внешней системе |
| ''externalCheck'' | integer | да | Номер чека во внешней системе |
| ''bonusSpentSum'' | integer | да | Сумма оплаты бонусами |
| ''discountSum'' | integer | да | Сумма скидки |
| ''bonusAccruedSum'' | integer | да | Сумма начисляемых бонусов |
| ''moneySpentSum'' | integer | да | Сумма оплаты деньгами |
| ''checkData'' | string |  | Содержимое чека (строки, оплаты) в формате JSON |

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

==== Отмена внешней продажи ====
**''POST /api/v0/external/return_check''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''checkGuid'' | uuid | да | GUID чека, переданный при регистрации продажи |

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

===== Импорт данных =====

==== Импорт в группу счетов ====
**''POST /api/v0/import_data/import_parsed_rk_pds_row''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accountGroupId'' | integer | да | Идентификатор группы счетов |
| ''rows'' | массив [[#csvrkparseditemdto|CsvRkParsedItemDto]] | да | Строки отчёта |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''taskId'' | string | да | Идентификатор фоновой задачи |
| ''status'' | string |  | Статус; по умолчанию ''"started"'' |

==== Импорт распарсенных потрат в БД ====
**''POST /api/v0/import_data/import_parsed_spending''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''rows'' | массив [[#spendingimportitemdto|SpendingImportItemDto]] | да | Строки отчёта |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''taskId'' | string | да | Идентификатор фоновой задачи |
| ''status'' | string |  | Статус; по умолчанию ''"started"'' |

==== Импорт базы предыдущей версии Telegram-бота ====
**''POST /api/v0/import_data/import_previous_telegram_bot_db''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''db_file'' | файл | да |  |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''overallRows'' | integer | да | Всего строк |
| ''importedRows'' | integer | да | Импортировано строк |

==== Проверка статуса задачи импорта по task_id ====
**''GET /api/v0/import_data/import_task_status''**\\
Авторизация: требуется

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

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''task_id'' | строка запроса | string | да | Идентификатор фоновой задачи импорта |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''doc'' | массив любой |  |  |
| ''log'' | массив любой |  |  |
| ''status'' | [[#backgroundtaskstate|BackgroundTaskState]] |  | Статус; по умолчанию ''"NONE"'' |
| ''text'' | string |  | Текст |

==== Загрузка (импорт) счетов из файла обмена (CSV) ====
**''POST /api/v0/import_data/parse_rk_pds_csv''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''csv_file'' | файл | да | CSV-файл |
| ''parse_config'' | string |  | Настройки разбора файла (JSON) |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''row'' | integer |  | Строка |
| ''card'' | string(50) |  | Карта |
| ''restSum'' | number |  |  |
| ''rkCode'' | integer |  | Код скидки (бонуса) r_keeper |
| ''rkBonusTypeCode'' | integer |  | Код типа бонуса r_keeper |
| ''fName'' | string(100) |  | Имя |
| ''lName'' | string(100) |  | Фамилия |
| ''mName'' | string(100) |  | Отчество |
| ''phone1'' | string |  |  |
| ''phone2'' | string |  |  |
| ''email'' | string (e-mail) |  | Адрес e-mail |
| ''birthday'' | date |  | Дата рождения |
| ''text'' | string |  | Текст |
| ''sex'' | string |  | Пол |
| ''parseInfo'' | массив string |  | Результат разбора файла |
| ''screenMessage'' | string(255) |  | Сообщение для экрана |
| ''checkMessage'' | string(255) |  | Сообщение для печати |
| ''wallet'' | string(50) |  |  |
| ''validTo'' | date |  |  |

==== Парсинг CSV файла с потратами (идентификатор, сумма) ====
**''POST /api/v0/import_data/parse_spending_csv''**\\
Авторизация: требуется

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''csv_file'' | файл | да | CSV-файл |
| ''parse_config'' | string |  | Настройки разбора файла (JSON) |

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

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''row'' | integer |  | Строка |
| ''identifier'' | string(50) |  | Идентификатор |
| ''amount'' | integer |  | Сумма |
| ''parseInfo'' | массив string |  | Результат разбора файла |

===== Инфокиоск =====

==== Страница инфокиоска (ввод карты) ====
**''GET /screen/client/get/''**\\
Авторизация: **не требуется**

**Ответ 200:** ''text/html''.

==== Поиск гостя на инфокиоске ====
**''POST /screen/client/get/''**\\
Авторизация: **не требуется**

**Тело запроса** (''application/x-www-form-urlencoded'') — объект ''post (Body_find_guest_screen_client_get)'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''code'' | string | да | Код |

**Ответ 200:** ''text/html''.

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

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

==== BackgroundTaskState ====
Перечисление (string). Значения: ''none'', ''process'', ''ok'', ''error''.
''none'' — нет задачи, ''process'' — выполняется, ''ok'' — завершена успешно, ''error'' — завершена с ошибкой

==== CsvRkParsedItemDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''row'' | integer |  | Строка |
| ''card'' | string(50) |  | Карта |
| ''restSum'' | number |  |  |
| ''rkCode'' | integer |  | Код скидки (бонуса) r_keeper |
| ''rkBonusTypeCode'' | integer |  | Код типа бонуса r_keeper |
| ''fName'' | string(100) |  | Имя |
| ''lName'' | string(100) |  | Фамилия |
| ''mName'' | string(100) |  | Отчество |
| ''phone1'' | string |  |  |
| ''phone2'' | string |  |  |
| ''email'' | string (e-mail) |  | Адрес e-mail |
| ''birthday'' | date |  | Дата рождения |
| ''text'' | string |  | Текст |
| ''sex'' | string |  | Пол |
| ''parseInfo'' | массив string |  | Результат разбора файла |
| ''screenMessage'' | string(255) |  | Сообщение для экрана |
| ''checkMessage'' | string(255) |  | Сообщение для печати |
| ''wallet'' | string(50) |  |  |
| ''validTo'' | date |  |  |

==== SpendingImportItemDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''row'' | integer |  | Строка |
| ''identifier'' | string(50) |  | Идентификатор |
| ''amount'' | integer |  | Сумма |
| ''parseInfo'' | массив string |  | Результат разбора файла |