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

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

Удостоверяване

Всички заявки използват Bearer токен, издаден за вашия Hype Reports акаунт.

Хедър:

Authorization: Bearer <your_api_token>

Ще получите:

integration_id
api_token

Базов URL адрес

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

Разработка: https://es.dev.hype-software.com
Продукция: https://es.hype-software.com

Диаграми на процесите

Първоначална синхронизация на интеграцията

HES (създава задачи)                         Hype Reports (HR)
        |                                           |
        |  GET /tasks/hype-reports/{entity}         |  (извличане)
        |<------------------------------------------|
        |  връща задачи за обектите                     |
        |------------------------------------------>|
        |                                           |
        |  PUT /tasks/hype-reports/{entity}         |  (отчитане)
        |<------------------------------------------|
        |  записва стойности и връзки              |
        |------------------------------------------>|
        |                                           |
        |  повтаря се за всеки включен тип обект

Процес за заявяване на справка

text

Hype Reports -> HES: POST /api/v1/integrations/{integration_id}/reports/{report}
HES -> Hype Reports: 202 Accepted, jobId, pollUrl
Hype Reports -> HES: GET pollUrl (повтаря се, докато справката се обработва)
HES -> Hype Reports: статус, данни или грешка

За генериране на справка клиентът ви изпраща заявка и проверява резултата. HES управлява генерирането и промените на статуса асинхронно. Клиентът ви не отчита завършването на справка и не качва генерирани данни.

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

Уговорете Reports интеграцията за съответния клиент с поддръжката на Hype и получете идентификатора и Bearer токена ѝ. Продължете да обработвате задачи за справочните данни във вашия Reports клиент, докато интеграцията е в syncing.

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

Обект	Извличане на задачи	Отчитане на задачи
Категории	`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`

Ред и завършване на стъпките

Шаблонът на интеграцията определя кои обекти участват. Когато всички текущи типове за Reports са включени, процесът има 14 стъпки:

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

Всяка стъпка чака изходния си отговор и всички произлезли задачи за синхронизация. Проверявайте GET /api/hype-reports/integrations/{id}?include=pipeline за progress.step, progress.from, status и message на процеса. След завършване процесът става synced, а интеграцията active.

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

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

Отговорът е списък от задачи. Всяка съдържа id, request, status, meta и type, който определя действието:

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

Полето type на задачата описва действието върху обекта. Hype Reports винаги изпраща резултата от обработката към HES с HTTP PUT, включително за задачи от тип GET и POST. Тези PUT адреси служат за отчитане на задачи за синхронизация. При генериране на справки POST заявява справка, а GET проверява резултата ѝ; няма PUT операция за редактиране на генерирана справка.

GET

Значение: изпратете собствените си данни към HES.
Отговор: списък от ваши обекти.
Върнете [] за тип обект, който не съхранявате.

POST/PUT

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

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

Обект	Полета в `request`/успешния `response`
Категория	`id`, `name`
Основна категория	`id`, `name`
Фискално устройство	`id`, `name`, `is_active`
Меню	`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 id за всеки обект, който съхранявате; от него зависят филтрите и преобразуването на идентификаторите в резултатите.

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

Използвайте PUT, за да отчетете задачите:

PUT /tasks/hype-reports/categories
PUT /tasks/hype-reports/fiscalDevices
PUT /tasks/hype-reports/mainCategories
PUT /tasks/hype-reports/menus
PUT /tasks/hype-reports/saloons
PUT /tasks/hype-reports/tables
PUT /tasks/hype-reports/users

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

json

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

Забележки:

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

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

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

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

Адрес за заявяване

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

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

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. Филтрите и максималните периоди зависят от справката:

Справка	Незадължителни филтри с Hype Reports идентификатори	Максимален период
`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 часа.

Филтрите трябва да съдържат идентификатори, съпоставени при синхронизацията. HES пропуска несъпоставените идентификатори; ако не останат стойности, не се прилага филтър за този тип обект.

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

json

{
  "date_from": "2025-01-01T00:00:00.000Z",
  "date_to": "2025-01-31T23:59:59.000Z",
  "user_ids": ["123", "456"]
}

Пример за 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"
}

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

GET /api/v1/report-data/{jobId} връща следните статуси:

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

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

GET /api/v1/report-data/{jobId}

Пример за чакаща справка:

json

{
  "jobId": "<report_job_id>",
  "status": "PENDING",
  "data": null
}

При status=COMPLETED структурата на data зависи от справката. За operator-revenue data е обект с period и results, по един елемент за оператор (тук е съкратен):

json

{
  "jobId": "<report_job_id>",
  "status": "COMPLETED",
  "data": {
    "results": [
      { "operatorId": "<hr_user_id>", "revenue": 123.45 }
    ]
  },
  "completed_at": "2026-02-04T12:34:56+00:00"
}

За revenue-by-menu, revenue-by-fiscal-device, revenue-by-main-category и revenue-by-category data е масив на най-горно ниво с по един ред за меню, фискално устройство, основна категория или категория:

Справка	Полета на реда
`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": "<report_job_id>",
  "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"
}

Всеки елемент съдържа accountTotal, масив items с quantity, salePrice и незадължително name, а може да съдържа и operatorId/operatorName, saloonId/saloonName, tableId/tableName и accountClosedAt. Незадължителните полета могат да са null или да липсват. При сметки на виртуални маси полетата за салон и маса могат да са null или да липсват.

При status=FAILED:

json

{
  "jobId": "<report_job_id>",
  "status": "FAILED",
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Parameter validation failed: date_from must be ISO 8601"
  }
}

Забележки:

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

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

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

При налични връзки HS идентификаторите се преобразуват във вашите HR идентификатори.
При липсващи връзки остават HS идентификатори.
operator-revenue преобразува operatorId във всеки елемент на results.
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 във всеки елемент на основния масив.

4) API за интеграции и опашки за синхронизация

Адаптерът Hype Reports предоставя и адреси за управление със същия Bearer токен:

Метод	Адрес	Цел
`GET`	`/api/hype-reports/integrations`	Списък с интеграциите, видими за Hype Reports акаунта
`GET`	`/api/hype-reports/integrations/{integration_id}`	Подробности за интеграция
`GET`	`/api/hype-reports/integrations/{integration_id}/queue-jobs`	Списък с чакащи задания за синхронизация на обекти
`DELETE`	`/api/hype-reports/integrations/{integration_id}/queue-jobs/{job_id}`	Изтриване на едно чакащо задание, отговор 204
`DELETE`	`/api/hype-reports/integrations/{integration_id}/queue-jobs`	Изчистване на всички чакащи задания за интеграцията, отговор 204

Всеки елемент на опашката съдържа id, entity, request_method, payload, source с id и name, status и error_msg.

Този адрес е за задания за синхронизация на обекти, а не за проверка на генерирани справки. За статус на справка използвайте GET /api/v1/report-data/{jobId}.

Чести грешки

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 от страната на Reports ​

Удостоверяване ​

Базов URL адрес ​

Диаграми на процесите ​

Първоначална синхронизация на интеграцията ​

Процес за заявяване на справка ​

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

Ред и завършване на стъпките ​

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

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

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

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

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

Адрес за заявяване ​

Данни на заявката ​

Отговор ​

Статуси на справките ​

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

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

4) API за интеграции и опашки за синхронизация ​

Чести грешки ​

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

Удостоверяване

Базов URL адрес

Диаграми на процесите

Първоначална синхронизация на интеграцията

Процес за заявяване на справка

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

Ред и завършване на стъпките

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

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

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

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

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

Адрес за заявяване

Данни на заявката

Отговор

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

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

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

4) API за интеграции и опашки за синхронизация

Чести грешки