hype-reports

Интеграция с Hype Reports

Страницата описва интеграцията на Hype Reports клиент с Hype Exchange Service (HES) за синхронизация на категории, фискални устройства, основни категории, менюта, салони, маси и потребители, както и за заявяване на справки и проверка на статуса им.

Всички заявки използват Bearer токен за Hype Reports акаунта:

Authorization: Bearer <api_token>

Ще получите:

integration_id
api_token

Базов URL адрес

Използвайте предоставената ви HES среда.

1) Първоначална синхронизация

HES поддържа седем типа обекти. Шаблонът на интеграцията определя конкретните стъпки. Вижте пълния процес на интеграция за реда на стъпките и условията за готовност.

Hype Reports извлича задачи за всички включени типове обекти и връща резултатите чрез съответните PUT адреси. Таблицата изброява адресите, а не реда на стъпките.

Обект	Извличане на задачи	Отчитане на задачи
Категории	GET /tasks/hype-reports/categories	PUT /tasks/hype-reports/categories
Фискални устройства	GET /tasks/hype-reports/fiscalDevices	PUT /tasks/hype-reports/fiscalDevices
Основни категории	GET /tasks/hype-reports/mainCategories	PUT /tasks/hype-reports/mainCategories
Менюта	GET /tasks/hype-reports/menus	PUT /tasks/hype-reports/menus
Салони	GET /tasks/hype-reports/saloons	PUT /tasks/hype-reports/saloons
Маси	GET /tasks/hype-reports/tables	PUT /tasks/hype-reports/tables
Потребители	GET /tasks/hype-reports/users	PUT /tasks/hype-reports/users

Задачите за маси идват със saloonId, вече заменен с идентификатора на салона в Hype Reports, или 0, ако сте потвърдили салона с {}. HES съпоставя масите само по id и не чете saloonId от вашия отговор.

Типове задачи

GET

Значение: изпратете собствените си данни към HES.
response може да е списък или [].
Върнете [], ако не съхранявате записи от този тип.

POST/PUT

Значение: приложете или съпоставете изходния обект.
response трябва да е един обект със съществуващия ви HR идентификатор.
Това създава връзка HS ID <-> HR ID и предотвратява дублиране.
HES не изпраща DELETE задачи. Запис, изтрит в Hype, пристига като PUT задача с нулирани полета (празни низове или нули, например "name": "").

Данни за обектите

Обект	Полета
Категория	id, name
Фискално устройство	id, name, is_active
Основна категория	id, name
Меню	id, name, startDate, endDate, isActive, isDefault
Салон	id, name, width, height, order
Маса	id, name, saloonId, x, y, width, height
Потребител	id, firstName, middleName, lastName, position, email, phone

Идентификаторите могат да са низове или цели числа. Връщайте постоянен Hype Reports идентификатор за всеки обект, който съхранявате; от него зависят филтрите и съпоставянето в резултатите.

Заявка за отчитане на задачи

Формат на данните:

json

[
  {
    "entity_task_id": "",
    "status": 200,
    "response": {
      "id": "",
      "name": "Table 1",
      "saloonId": "",
      "x": 0,
      "y": 0,
      "width": 100,
      "height": 100
    }
  }
]

Забележки:

При POST/PUT задачи response трябва да е един обект.
При GET задачи response може да е списък или [].
response: {} се приема и позволява синхронизацията да продължи, но не създава използваема връзка за HR идентификатора. Използвайте го само за салони и маси, които не съхранявате. Без връзка тези идентификатори не могат да се използват като филтри и HES не може да ги преобразува в резултатите. Не го използвайте за категории, фискални устройства, основни категории, менюта или потребители: следващата промяна на такъв запис в Hype не може да бъде доставена и спира синхронизацията на цялата интеграция, докато връзката не бъде оправена.

Предотвратяване на дублиране

Ако вече имате същата категория, фискално устройство, основна категория, меню, салон, маса или потребител, върнете съществуващия HR идентификатор в POST/PUT отговора. HES ще свърже идентификаторите, вместо да създава дубликати.

2) Заявяване на справки

Вашият Reports клиент заявява справка и проверява статуса и резултата ѝ. HES управлява генерирането и промените на статуса асинхронно.

POST /api/v1/integrations/{integration_id}/reports/

Поддържани справки:

operator-revenue
revenue-by-menu
revenue-by-fiscal-device
revenue-by-main-category
revenue-by-category
orders-summary

Всички справки изискват:

date_from: дата и час по ISO 8601 или YYYY-MM-DD.
date_to: дата и час по ISO 8601 или YYYY-MM-DD.

date_to трябва да е равна на или след date_from. Филтрите и максималните периоди зависят от справката:

Справка	Незадължителни филтри с HR идентификатори	Максимален период
operator-revenue	user_ids	31 дни
revenue-by-menu	menu_ids	31 дни
revenue-by-fiscal-device	fiscal_device_ids	31 дни
revenue-by-main-category	main_category_ids	31 дни
revenue-by-category	category_ids	31 дни
orders-summary	user_ids, saloon_ids, table_ids	1 ден

Периодът се сравнява в цели дни, като остатъкът се пренебрегва: справка с 31 дни приема всеки период под 32 дни, а orders-summary приема всеки период под 48 часа.

Всички идентификатори във филтрите трябва да са Hype Reports идентификатори, съпоставени чрез задачи. HES ги преобразува преди генериране на справката. Несъпоставените се пропускат; ако не останат стойности, не се прилага филтър за този тип обект.

Пример за operator-revenue:

json

{
  "date_from": "2025-01-01T00:00:00.000Z",
  "date_to": "2025-01-31T23:59:59.000Z",
  "user_ids": ["hr-user-1", "hr-user-2"]
}

Пример за orders-summary:

json

{
  "date_from": "2026-07-08T00:00:00.000Z",
  "date_to": "2026-07-08T23:59:59.000Z",
  "user_ids": ["hr-user-7"],
  "saloon_ids": ["hr-saloon-10"],
  "table_ids": ["hr-table-20"]
}

При успех HES връща 202:

json

{
  "jobId": "<report_job_id>",
  "pollUrl": "https://es.dev.hype-software.com/api/v1/report-data/<report_job_id>",
  "message": "Report request accepted and queued for processing"
}

3) Проверка на статуса на справка

GET /api/v1/report-data/

Статуси на справката:

PENDING: заявката е приета и чака генериране.
PROCESSING: справката се генерира.
POST_PROCESSING_PENDING: чака съпоставяне на идентификатори и форматиране.
POST_PROCESSING: последващата обработка се изпълнява.
COMPLETED: завършило успешно; данните са налични.
FAILED: генерирането е завършило с грешка; подробностите са налични.
CANCELLED: справката е отменена.

Отговор при чакаща справка:

json

{
  "jobId": "",
  "status": "PENDING",
  "data": null
}

Структурата на data при завършена справка зависи от справката:

operator-revenue: обект с period и results, по един елемент за оператор.
revenue-by-menu: масив на най-горно ниво с редове {menuId, menuName, total}.
revenue-by-fiscal-device: масив на най-горно ниво с редове {fiscal_device_id, fiscal_device_name, revenue}.
revenue-by-main-category: масив на най-горно ниво с редове {main_category_id, main_category_name, revenue}; идентификаторът и името могат да са null.
revenue-by-category: масив на най-горно ниво с редове {category_id, category_name, revenue}; идентификаторът и името могат да са null.

За orders-summary data е масив на най-горно ниво с по един елемент за всяка приключена сметка:

json

{
  "jobId": "",
  "status": "COMPLETED",
  "data": [
    {
      "saloonId": "hr-saloon-10",
      "saloonName": "Main hall",
      "tableId": "hr-table-20",
      "tableName": "Table 1",
      "accountTotal": 123.45,
      "items": [
        { "name": "Coffee", "quantity": 2, "salePrice": 9.5 }
      ],
      "operatorId": "hr-user-7",
      "operatorName": "Mila Ivanova",
      "accountClosedAt": "2026-07-08T12:30:00.000Z"
    }
  ],
  "completed_at": "2026-07-08T12:31:00+00:00"
}

Незадължителните полета могат да са null или да липсват. При сметки на виртуални маси полетата за салон и маса също могат да са null или да липсват.

HES пази данните на завършените справки поне 7 дни след completed_at. Ежедневно почистване в 03:00 UTC изтрива по-старите резултати, така че резултатът се премахва 7 до 8 дни след завършването. След това проверката на неговия jobId връща 404. Ако резултатите ви трябват по-дълго, запазете ги при себе си.

Съпоставяне на идентификатори в резултатите

HES преобразува идентификаторите в резултатите обратно в Hype Reports идентификатори:

operator-revenue: operatorId
revenue-by-menu: menuId
revenue-by-fiscal-device: fiscal_device_id
revenue-by-main-category: main_category_id
revenue-by-category: category_id
orders-summary: operatorId, saloonId, tableId

Ако няма връзка, резултатът запазва оригиналния Hype идентификатор.

Чести грешки

422 Грешка при валидация

Невалидна дата или date_to преди date_from.
Период над 1 ден за orders-summary или над 31 дни за останалите справки.
Тялото е {"error": 1, "message": "Report validation failed", "errors": {...}}, където errors съдържа съобщенията за всяко невалидно поле.

403 Неразрешен достъп

При заявяване на справка акаунтът на токена не участва в интеграцията: {"message": "Requesting account is not part of this integration"}.
При проверка на статуса акаунтът не участва в интеграцията на справката или е акаунтът, който генерира справката: {"message": "Unauthorized"}.

404 Не е намерено

Справка с това име не съществува в каталога на HES или проверяваният jobId е непознат: {"message": "Report not found"}.
Непознат integration_id също връща 404 със стандартното тяло {"error": 1, "message": "..."}.

hype-reports ​

hype-reports