Integration from setup to go-live

An integration connects one Hype Server account to an account on your platform through Hype Exchange Service (HES). HES coordinates the work and translates IDs between the two systems.

Integration type	What it enables	What must happen before use
hype-custom	Hype sends catalog changes; your platform submits orders and receives status updates.	Initial sync, then manual mapping in the Hype Server back-office UI, then an end-to-end order check.
hype-reports	Hype sends reporting reference data; your client requests reports and retrieves their results.	Initial sync with usable ID mappings, then an end-to-end report check.

The onboarding sequence is:

1. Configure the integration and obtain credentials.
2. Run your client's task processing throughout the initial synchronization.
3. Wait for the pipeline to become synced and the integration to become active.
4. For hype-custom, complete the manual mappings in Hype Server.
5. Verify the complete order or report flow, then enable normal use.

Active is not the custom integration's go-live signal

active means the initial pipeline has finished. It does not certify that a person has paired order statuses, delivery channels, and payment types. Those mappings must be saved after activation, before sending orders.

1. Configure the connection

Create the integration for the intended Hype customer in the Hype Server back office, with Hype support where needed. Choose the integration type and supply the settings for the connected platform. For custom integrations, confirm the source menu used for item prices and supplements.

Obtain the integration ID, account bearer token, and environment URL. Store the credentials for the correct account and environment; see authentication and environments.

Have your task worker ready before starting synchronization. Creating an integration starts its initial sync; if your client is not processing tasks, the pipeline waits. Arrange connection setup with Hype support.

2. Understand a synchronization step

A pipeline is an ordered list of entity types to fetch. One step can produce many tasks, so "step 4" does not mean "the fourth record." The enabled entities in the integration template determine the actual steps and total.

For each step:

1. HES collects the records needed for the current entity type.
2. When HES needs your records, your client receives a task whose type is GET; return an array of records with stable IDs.
3. When Hype records need to be applied in your system, your client receives create/update tasks; process each task and return your corresponding record ID.
4. HES uses the results to link records between the systems.
5. The next step starts only after all work for the current step has finished successfully. Keep polling and reporting results while synchronization is in progress.

Your worker uses GET /tasks/{platform}/{entity} to fetch work and PUT /tasks/{platform}/{entity} to report results, where {platform} is hype-custom or hype-reports. The task's type describes the requested operation; it is separate from the HTTP method used to poll or acknowledge it.

Task type	What your worker does	Successful response
GET	Return your existing records for that entity type.	An array of records with stable IDs.
POST / PUT	Create, match, or update a record in your system. Reuse an existing ID when it is the same record.	A single object containing your resulting id.

HES does not currently 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": ""); check for this case before applying a PUT.

Report entity_task_id, the processing status, and response for each task. An HTTP 204 from the acknowledgement endpoint means the result was accepted; it does not mean the whole pipeline has completed. Keep polling all enabled entity endpoints and make handlers safe to repeat.

What the statuses mean

Integration status	Meaning and next action
inactive	The integration is not running. It may be newly created or disabled.
syncing	Initial synchronization is underway. Keep your client's task processing running.
active	The initial pipeline finished. Complete the type-specific go-live steps below.
aborted	Synchronization failed or was stopped. Inspect the pipeline message and resolve the cause with Hype support before resuming or re-running it.
error	An integration error needs investigation.

Inspect GET /api/hype-custom/integrations/{id}?include=pipeline or GET /api/hype-reports/integrations/{id}?include=pipeline for your integration type. When a pipeline exists, the response includes pipeline.status, pipeline.progress.step, pipeline.progress.from, pipeline.progress.task_id, and pipeline.message.

Pipeline states are pending, processing, synced, failed, and stopped. A pipeline can wait indefinitely for an unreported task. If a step fails, earlier completed work remains; restarting does not undo it.

3. Hype Custom onboarding

The standard custom configuration has the following 11 steps. An integration with a narrower template can have fewer steps.

Step	Source and entity	What the step accomplishes
1	Hype: categories	Create or match categories on your platform and link their IDs. Items depend on these links.
2	Hype: saloons	Synchronize venue areas, before their tables.
3	Hype: tables	Synchronize tables with their mapped saloon references.
4	Hype: items	Synchronize the catalog, including category references and menu-specific prices.
5	Hype: supplements	Synchronize supplements using the item mappings established in step 4.
6	Hype: order statuses	Store Hype's available statuses for later manual pairing.
7	Hype: delivery channels	Store Hype's available delivery channels for later manual pairing.
8	Hype: payment types	Store Hype's available payment types for later manual pairing.
9	Your platform: order statuses	Answer a GET task on orderRequestStatus with your statuses and IDs.
10	Your platform: delivery channels	Answer a GET task on orderDeliveryChannels with your channels and IDs.
11	Your platform: payment types	Answer a GET task on orderPaymentTypes with your payment types and IDs.

Steps 6–11 collect the choices from both systems. They do not automatically decide which status, delivery channel, or payment type means the same thing in each system. Matching display names alone does not establish an ID mapping.

If your platform does not model saloons and tables, the custom adapter permits acknowledging those tasks with response: {}. That advances synchronization without a table mapping; omit tableId from subsequent orders.

After active: map the values in Hype Server

Once the pipeline is synced and the integration is active, open that integration in the Hype Server back-office UI and complete its manual mappings:

Map these values	Why orders need them
Order request statuses	Translate your order lifecycle into Hype's statuses and translate updates back.
Delivery channels	Associate your delivery or collection options with the corresponding Hype channels.
Payment types	Associate your payment methods with the corresponding Hype payment types.

Pair the corresponding values and save the mappings. Cover every value your integration will send or receive. For example, your payment type ID card-online and Hype's card payment ID are separate identifiers even if both are displayed as "Card."

If a needed choice is missing, check that the corresponding bootstrap task returned that system's records. Correct the source data or task handling, refresh it through the supported sync flow, then complete the mapping. Uploading a new status/channel/payment value through a webhook makes the value available; it does not replace this manual pairing step.

Verify an order before go-live

1. Confirm that active/synced is reached and the manual mappings are saved.
2. Send a test order through POST /webhook/hype-custom/orderRequests, using mapped items, supplements, statuses, channels, and payment types. Include a table only when it is mapped.
3. HES accepts the webhook with 204, translates the IDs, and queues delivery to Hype Server. Confirm the order actually appears in Hype; webhook acceptance alone is insufficient.
4. Change the order's status in Hype. Poll /tasks/hype-custom/orderRequests, apply the returned status update, and acknowledge it.
5. Enable real order traffic once that round trip succeeds. Keep processing catalog and order-status tasks during normal operation, and review manual mappings when new choices are introduced.

See the custom developer guide for worker implementation and the custom API reference for payloads.

4. Hype Reports onboarding

Reports need reference IDs so HES can translate your filters into Hype IDs and translate IDs in the results back to your system. Return the ID of an existing Reports record when it already represents the same Hype record.

With all current reporting entities enabled, the pipeline has two phases:

Phase	Step order	What your Reports client does
Hype supplies reference data (steps 1–7)	Categories → saloons → tables → menus → users → fiscal devices → main categories	Poll /tasks/hype-reports/{entity}, process the create/update tasks, and return the corresponding Reports IDs. These responses establish the ID mappings.
Reports supplies its records (steps 8–14)	Categories → fiscal devices → main categories → menus → saloons → tables → users	Answer the GET tasks with arrays of your records, or [] for an entity type you do not retain. HES records this side's values.

Each entity step brings a different set of reference records into HES:

Entity	Meaning
Categories	Item category IDs and names. Mapped category IDs can be used by the revenue-by-category report.
Saloons	Venue areas. Their IDs are used by table relationships and supported report filters.
Tables	Tables within those areas, including each table's saloon reference.
Menus	Menus with their dates and active/default flags. Mapped menu IDs can be used by the revenue-by-menu report.
Users	Staff/operator records. Mapped user IDs can be used by reports that support user filters.
Fiscal devices	Fiscal device IDs, names, and active flags. Mapped fiscal device IDs can be used by the revenue-by-fiscal-device report.
Main categories	Main category IDs and names. Mapped main category IDs can be used by the revenue-by-main-category report.

The endpoint entity names are categories, saloons, tables, menus, users, fiscalDevices, and mainCategories. The actual pipeline total depends on the integration template. Saloons precede tables because a table references its saloon.

After the pipeline finishes, the integration becomes active. Reports mappings are established through task responses; the custom integration's manual status/channel/payment mapping step does not apply. Check that the entities you need have usable ID mappings before requesting a report. Acknowledging an entity without an ID can let synchronization finish without establishing that mapping. Only do this for saloons and tables: if a category, menu, user, fiscal device, or main category was acknowledged without an ID, the next change to that record in Hype stops synchronization for the whole integration until the mapping is fixed.

Verify a report before go-live

1. Request a small report with POST /api/v1/integrations/{integration_id}/reports/{report}. Send supported filters using your mapped Reports IDs.
2. HES returns 202, a jobId, and a pollUrl, and handles generation asynchronously.
3. Poll the returned pollUrl until the report is COMPLETED, FAILED, or CANCELLED. Your client reads these statuses; HES updates them as processing progresses.
4. For COMPLETED, read data and verify the expected date range, filtering, and IDs. Handle failure/cancellation instead of polling indefinitely. Keep processing reference-data tasks as those records change.

Do not test an ID filter with unmapped values: HES drops unmapped filter IDs, and if none remain no filter is applied for that entity type. Confirm the mapping first so the report does not cover a broader set of records than intended.

See the Reports developer guide for entity payloads, report types, limits, and request/response examples.