Hype Reports Integration (Reports Side)

This document describes how a Hype Reports client integrates with the Hype Exchange Service (HES) for category, fiscal device, main category, menu, saloon, table, and user synchronization and for report requests.

Authentication

All requests use a Bearer token issued for your Hype Reports account.

Header:

Authorization: Bearer <your_api_token>

You will receive:

• integration_id
• api_token

Base URL

Use the HES environment you were provided:

• DEV: https://es.dev.hype-software.com
• LIVE: https://es.hype-software.com

Flow Diagrams

Initial integration sync

HES (creates tasks)                         Hype Reports (HR)
        |                                           |
        |  GET /tasks/hype-reports/{entity}         |  (poll)
        |<------------------------------------------|
        |  returns entity tasks                     |
        |------------------------------------------>|
        |                                           |
        |  PUT /tasks/hype-reports/{entity}         |  (ack)
        |<------------------------------------------|
        |  stores values + ID mappings              |
        |------------------------------------------>|
        |                                           |
        |  repeat for every enabled entity type

Report Request Flow

Hype Reports -> HES: POST /api/v1/integrations/{integration_id}/reports/{report}
HES -> Hype Reports: 202 Accepted, jobId, pollUrl
Hype Reports -> HES: GET pollUrl (repeat while processing)
HES -> Hype Reports: status, data or error

For report generation, your client sends the request and polls the result. HES handles generation and status transitions asynchronously. Your client does not submit report completion or upload generated report data.

1) Initial sync

Arrange the Reports integration for the intended customer with Hype support and obtain its integration ID and bearer token. Keep your Reports client processing reference-data tasks while the integration is syncing.

The current configuration supports seven entity types. Poll and acknowledge every type enabled in your integration:

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

Pipeline order and completion

The integration template determines which entities participate. With all current reporting entities enabled, the pipeline has 14 steps:

1. Hype supplies categories, saloons, tables, menus, users, fiscal devices, and main categories, in that order. HES creates tasks on the Reports side; return your existing or newly created Reports IDs to establish mappings.
2. HES asks Reports for categories, fiscal devices, main categories, menus, saloons, tables, and users, in that order, through GET-type tasks. Return arrays of your records, or [] for entity types you do not retain.

Each step waits for its source response and all resulting synchronization tasks. Inspect GET /api/hype-reports/integrations/{id}?include=pipeline for the pipeline's progress.step, progress.from, status, and message. Pipeline completion sets it to synced and the integration to active.

Reports uses the ID mappings established by task responses. It does not require the custom integration's manual status/channel/payment mapping step. Before normal use, verify that the reference IDs needed for report filters and results have been mapped, then request a small report and check its completed result. Keep polling reference-data tasks after activation.

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.

The response is a list of tasks. Each task contains id, request, status, meta, and a type that defines what to do:

Task Types

The task's type describes the entity operation to process. Hype Reports always submits the processing result to HES with HTTP PUT, including for GET- and POST-type tasks. These PUT endpoints acknowledge synchronization tasks. Report generation uses POST to request a report and GET to poll its result; there is no PUT operation for editing a generated report.

GET

• Meaning: "Send your own data to HES."
• Response shape: return a list of your entities.
• Return [] for an entity type you do not retain.

POST/PUT

• Meaning: "Apply or map the source entity."
• Response shape: return a single object with your existing HR ID.
• This creates a mapping (HS ID <-> HR ID) and prevents duplication.
• 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 in request/successful response
Category	id, name
Main category	id, name
Fiscal device	id, name, is_active
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 whenever the entity is retained; report filters and result mapping depend on it.

Task Update Request

Use PUT to acknowledge tasks:

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

Payload format:

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

Notes:

• For POST/PUT tasks, response must be a single object.
• For GET tasks, response can be a list or [].
• A successful response: {} is accepted and advances the sync without establishing a usable HR-ID mapping. Use it only for saloons and tables you do not retain; their HR IDs then cannot be used as report filters and HES cannot translate their IDs in report 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 your existing HR ID in the POST/PUT response. HES will map the IDs instead of creating duplicates.

2) Request Reports

Request Endpoint

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

Supported reports:

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

Request Payload

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 are report-specific:

Report	Optional filters (Hype Reports 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.

Filter values must be IDs established by entity sync. HES omits unmapped IDs; if no 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": ["123", "456"]
}

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

Response

On success, HES returns 202 with a job ID:

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

Report Statuses

Report status values returned by GET /api/v1/report-data/{jobId}:

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

3) Poll Report Status

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

Example while the report is pending:

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

When status=COMPLETED, the shape of data depends on the report. For operator-revenue, data is an object with period and results, one entry per operator (abbreviated here):

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

For revenue-by-menu, revenue-by-fiscal-device, revenue-by-main-category, and revenue-by-category, data is a root array with one row per menu, fiscal device, main category, or category:

Report	Row fields
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; the ID and name can be null
revenue-by-category	category_id, category_name, revenue; the ID and name can be null

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

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

Each entry contains accountTotal, an items array (quantity, salePrice, and optional name), and may contain operatorId/operatorName, saloonId/saloonName, tableId/tableName, and accountClosedAt. Optional fields can be null or omitted. For accounts created on a virtual table, saloon and table fields can be null or omitted.

When status=FAILED:

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

Notes:

• data is always present; it is null until status=COMPLETED.
• completed_at is only present when status=COMPLETED.
• error is only present when status=FAILED.
• 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 maps IDs in report results:

• If mappings exist, HS IDs are translated to your HR IDs.
• If mappings are missing, IDs will remain as HS IDs.
• operator-revenue maps operatorId in each results entry.
• revenue-by-menu maps menuId, revenue-by-fiscal-device maps fiscal_device_id, revenue-by-main-category maps main_category_id, and revenue-by-category maps category_id.
• orders-summary maps operatorId, saloonId, and tableId in each root-array item.

4) Integration and Sync Queue API

The Hype Reports adapter also exposes operational endpoints using the same Bearer token:

Method	Endpoint	Purpose
GET	/api/hype-reports/integrations	List integrations visible to the Hype Reports account
GET	/api/hype-reports/integrations/{integration_id}	Read one integration
GET	/api/hype-reports/integrations/{integration_id}/queue-jobs	List queued entity-sync jobs
DELETE	/api/hype-reports/integrations/{integration_id}/queue-jobs/{job_id}	Remove one queued sync job (204)
DELETE	/api/hype-reports/integrations/{integration_id}/queue-jobs	Clear all queued sync jobs for the integration (204)

Each queue item contains id, entity, request_method, payload, source (id and name), status, and error_msg.

The queue endpoint is for entity synchronization jobs, not for polling report generation. Continue to use GET /api/v1/report-data/{jobId} for report status.

Common Errors

422 Validation error

• Happens when a date string is invalid, date_to is before date_from, or the range exceeds the report's limit (1 day for orders-summary, 31 days for the others).
• 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: your account is not part of the integration. The body is {"message": "Requesting account is not part of this integration"}.
• When polling: your account is not part of the report's integration, or it is the account that generates the report. The body is {"message": "Unauthorized"}.

404 Not found

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