hype-reports

Hype Reports integration

This page describes how a Hype Reports client integrates with Hype Exchange Service (HES) to synchronize categories, fiscal devices, main categories, menus, saloons, tables, and users, and to request and poll reports.

All requests use a Bearer token for the Hype Reports account:

Authorization: Bearer <api_token>

You will receive:

• integration_id
• api_token

Base URL

Use the HES environment you were provided.

1) Initial sync

HES supports seven entity types. The integration template determines the actual steps. See the complete integration flow for the step order and readiness requirements.

Hype Reports polls all enabled entity endpoints and returns results through their PUT endpoints. The table lists endpoints, not the pipeline step order.

Entity	Poll tasks	Acknowledge tasks
Categories	GET /tasks/hype-reports/categories	PUT /tasks/hype-reports/categories
Fiscal devices	GET /tasks/hype-reports/fiscalDevices	PUT /tasks/hype-reports/fiscalDevices
Main categories	GET /tasks/hype-reports/mainCategories	PUT /tasks/hype-reports/mainCategories
Menus	GET /tasks/hype-reports/menus	PUT /tasks/hype-reports/menus
Saloons	GET /tasks/hype-reports/saloons	PUT /tasks/hype-reports/saloons
Tables	GET /tasks/hype-reports/tables	PUT /tasks/hype-reports/tables
Users	GET /tasks/hype-reports/users	PUT /tasks/hype-reports/users

Table tasks arrive with saloonId already set to your Hype Reports saloon ID, or 0 if you acknowledged that saloon with {}. HES maps tables by id only; it doesn't read saloonId from your response.

Task types

GET

• Meaning: send your own data to HES.
• response can be a list or [].
• Return [] if you do not retain records of that type.

POST/PUT

• Meaning: apply or match the source entity.
• response must be a single object with your existing HR ID.
• This creates an HS ID <-> HR ID mapping and prevents duplicates.
• HES does not send DELETE tasks. A record deleted in Hype arrives as a PUT task with its fields reset to empty or zero values (for example "name": "").

Entity payloads

Entity	Fields
Category	id, name
Fiscal device	id, name, is_active
Main category	id, name
Menu	id, name, startDate, endDate, isActive, isDefault
Saloon	id, name, width, height, order
Table	id, name, saloonId, x, y, width, height
User	id, firstName, middleName, lastName, position, email, phone

Entity IDs may be strings or integers. Return a stable Hype Reports ID for each entity you retain; report filters and ID mapping in results depend on it.

Task update request

Payload format:

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

Notes:

• For POST/PUT tasks, response must be a single object.
• For GET tasks, response can be a list or [].
• response: {} is accepted and advances synchronization, but creates no usable HR-ID mapping. Use it only for saloons and tables you do not retain. Without a mapping, those IDs cannot be used as report filters and HES cannot translate them in results. Do not use it for categories, fiscal devices, main categories, menus, or users: the next change to such a record in Hype cannot be delivered and stops synchronization for the whole integration until the mapping is fixed.

Deduplication rule

If you already have the same category, fiscal device, main category, menu, saloon, table, or user, return its existing HR ID in the POST/PUT response. HES will map the IDs instead of creating duplicates.

2) Request reports

Your Reports client requests a report and polls its status and result. HES handles generation and status transitions asynchronously.

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

Supported reports:

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

All reports require:

• date_from: ISO 8601 datetime or YYYY-MM-DD.
• date_to: ISO 8601 datetime or YYYY-MM-DD.

date_to must be on or after date_from. Filters and maximum ranges depend on the report:

Report	Optional filters (HR IDs)	Maximum range
operator-revenue	user_ids	31 days
revenue-by-menu	menu_ids	31 days
revenue-by-fiscal-device	fiscal_device_ids	31 days
revenue-by-main-category	main_category_ids	31 days
revenue-by-category	category_ids	31 days
orders-summary	user_ids, saloon_ids, table_ids	1 day

The range is compared in whole days, with any remainder dropped: a 31-day report accepts any range shorter than 32 days, and orders-summary accepts any range shorter than 48 hours.

All filter IDs must be Hype Reports IDs established through sync tasks. HES translates them before report generation. Unmapped IDs are omitted; if no mapped IDs remain, no filter is applied for that entity type.

Example (operator-revenue):

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

Example (orders-summary):

{
  "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"]
}

On success, HES returns 202:

{
  "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) Poll report status

GET /api/v1/report-data/

Report status values:

• PENDING: accepted, waiting for generation.
• PROCESSING: report generation is in progress.
• POST_PROCESSING_PENDING: queued for ID mapping and formatting.
• POST_PROCESSING: post-processing is running.
• COMPLETED: completed successfully; data is available.
• FAILED: report generation failed; error details are available.
• CANCELLED: the report was cancelled.

Pending response:

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

The shape of a completed data depends on the report:

• operator-revenue: an object with period and results, one entry per operator.
• revenue-by-menu: a root array of {menuId, menuName, total} rows.
• revenue-by-fiscal-device: a root array of {fiscal_device_id, fiscal_device_name, revenue} rows.
• revenue-by-main-category: a root array of {main_category_id, main_category_name, revenue} rows; the ID and name can be null.
• revenue-by-category: a root array of {category_id, category_name, revenue} rows; the ID and name can be null.

For orders-summary, data is a root array with one entry per closed account:

{
  "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"
}

Optional fields may be null or omitted. For accounts on virtual tables, saloon/table fields may be null or omitted.

HES keeps completed report data for at least 7 days after completed_at. A daily cleanup at 03:00 UTC deletes older results, so a result is removed 7 to 8 days after completion. After that, polling its jobId returns 404. Store results on your side if you need them longer.

ID mapping in report results

HES translates report result IDs back to Hype Reports IDs:

• 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

If no mapping exists, the result retains the original Hype ID.

Common errors

422 Validation error

• Invalid date or date_to before date_from.
• Range exceeds 1 day for orders-summary or 31 days for the other reports.
• The body is {"error": 1, "message": "Report validation failed", "errors": {...}}, where errors lists the messages for each failing field.

403 Unauthorized

• When requesting a report, the token's account is not part of the integration: {"message": "Requesting account is not part of this integration"}.
• When polling, the account is not part of the report's integration or is the account that generates the report: {"message": "Unauthorized"}.

404 Not found

• The report slug does not exist in the HES report catalog, or the polled jobId is unknown: {"message": "Report not found"}.
• An unknown integration_id also returns 404, with the standard {"error": 1, "message": "..."} body.