Device Details

Every integration authenticates with an X-API-Key that represents a single external device -- typically one physical POS terminal. The device determines who you are and what you may do: which organization and venue you act on behalf of, which desks you serve, and which operations your key is permitted to perform.

GET /v1/integrations/me returns that identity. It is shared infrastructure: the same endpoint backs the Cheers Loyalty, Counter Order, and Hybrid RevoUnion integrations.

When to Use It

Three practical uses:

1. Verify the API key at startup. A single call confirms the key is valid and provisioned before the first customer is served, rather than discovering it mid-transaction.
2. Decide which features to enable. The authorities array tells you what the key may do. Hide POS features the device is not permitted to use instead of letting the operator hit a 403 at the counter.
3. Populate receipt headers. The organization name and place (business unit) name printed on receipts come from this endpoint -- including the Hybrid RevoUnion deposit receipt.

Cache the response

Device identity changes rarely. Fetch it at startup and refresh periodically -- do not call it before every transaction.

Request

API: GET /v1/integrations/me

curl -X GET https://api.dev.votesess.com/v1/integrations/me \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "device-001",
  "name": "Bar Terminal 1",
  "authorities": ["INTEGRATION", "CREDIT", "ORDER", "REVO"],
  "organization": {
    "id": "org-001",
    "name": "Summer Festival Kft."
  },
  "place": {
    "id": "place-001",
    "name": "Main Stage Bar",
    "description": "Bar next to the main stage",
    "formattedAddress": "1051 Budapest, Example utca 1.",
    "placeStatus": "ACTIVE"
  },
  "relatedDesks": [
    { "id": "desk-001", "name": "Counter 1", "type": "COUNTER", "enabled": true },
    { "id": "desk-002", "name": "Table 5", "type": "TABLE", "enabled": false }
  ]
}

Field	Type	Description
id	string	The id of the device in the Cheers system.
name	string	Display name of the device (e.g. "Bar Terminal 1").
authorities	array	Permissions granted to this API key. See Authorities.
organization	object	The organization the device belongs to.
place	object	The venue (business unit) the device is assigned to.
relatedDesks	array	Desks this device serves.

Authorities

The authorities array determines which operations the API key may perform. A key without the matching authority receives 403 Forbidden with EXTERNAL_DEVICE_HAS_NO_RIGHT_AUTHORITY.

Authority	Grants
ORDER	Order handling.
ORDER_REFUND	Refunding orders.
SCAN	Scanning operations.
STATISTIC	Access to statistics.
INTEGRATION	General integration API access.
THIRD_PARTY_INTEGRATION	Third-party integration access.
CREDIT	Credit transactions -- required for Cheers Loyalty.
TICKET	Ticket handling.
KIOSK	Kiosk operation.
REVO	RevoUnion container deposits -- required for Hybrid RevoUnion.

Check authorities before enabling features

A key provisioned only for coupons cannot process payments. Reading authorities at startup lets you disable those POS features up front rather than failing at the counter.

Organization

Field	Type	Description
id	string	The id of the organization in the Cheers system.
name	string	Organization name. Printed on receipts.

Place

The venue (business unit) the device is assigned to.

Field	Type	Description
id	string	The id of the place in the Cheers system.
name	string	Place name. Printed on receipts.
description	string	Optional description of the place.
formattedAddress	string	Full formatted address.
avatarMedia	object	Optional place image (id, processing status, media type, and URIs in several sizes).
placeStatus	enum	Current status of the place. See below.

Place Statuses

Status	Description
DRAFT	The place is not published yet.
ACTIVE	The place is live and operating.
TEMPORARILY_CLOSED	The place is closed for now but will reopen.
PERMANENTLY_CLOSED	The place is closed for good.
HIDDEN	The place is not visible to customers.

Related Desks

The desks this device serves. Same shape as the desks returned by the Counter Order desk endpoints.

Field	Type	Description
id	string	The id of the desk in the Cheers system.
name	string	Display name of the desk (e.g. "Counter 1").
type	enum	COUNTER or TABLE.
enabled	boolean	Whether customers can currently place orders at this desk.

Changing desk availability

This endpoint reports desk state but does not change it. To suspend or resume ordering, use PUT /v1/integrations/desks/status.

Error Handling

Errors use the standard envelope:

{
  "errorModel": {
    "errorCode": "AUTHORIZATION",
    "message": "Human-readable description",
    "descriptors": []
  }
}

Status	Meaning
400	Malformed request.
401	Missing or invalid X-API-Key.
403	The key is valid but lacks access to the requested resource.
404	The device could not be resolved.

A 401 at startup almost always means the key was mistyped during terminal setup, or the device has been disabled in the Cheers CMS.