# Device Details (`/v1/integrations/me`) — LLM Reference

> Single-file, self-contained reference for the Cheers device identity endpoint.
> Source: https://integration.cheersapp.io/docs/integrations/device-details/overview
> OpenAPI spec: `basic-details-openapi` — https://integration.cheersapp.io/docs/api-reference/basic-details-openapi/votesess-integration-api-device-authentication

## What this endpoint does

Every Cheers integration authenticates with an `X-API-Key` representing 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 for, which desks you serve, and which
operations the key may perform.

`GET /v1/integrations/me` returns that identity. It is **shared infrastructure** — the same
endpoint backs all three integrations:

- Cheers Loyalty (POS API) — see `/llms/cheers-loyalty.md`
- Counter Order — see `/llms/counter-order.md`
- Hybrid RevoUnion — see `/llms/hybrid-revo-token.md`

## Environments

| Environment | Base URL |
|---|---|
| Development / Sandbox | `https://api.dev.votesess.com` |
| Production | `https://api.uniqpon.com` |

## Authentication

```
X-API-Key: YOUR_API_KEY
```

## When to call it

Three practical uses:

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

```
on POS startup:
    GET /v1/integrations/me
    if 200:
        cache device, organization, place, relatedDesks
        for each POS feature:
            enable only if its required authority is in authorities[]
    if 401:
        stop — key invalid or device disabled; alert the operator
```

**Cache the response.** Device identity changes rarely — fetch at startup and refresh
periodically. Do not call it before every transaction.

---

## Endpoint

`GET /v1/integrations/me`
Operation id: `getExternalDeviceByIntegration`
Headers: `X-API-Key`
Success: `200 OK`. Errors: `400`, `401`, `403`, `404`.

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

### Response — `IntegrationExternalDeviceResponse`

```json
{
  "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 | Required | Description |
|---|---|---|---|
| `id` | string | yes | Device id in the Cheers system. |
| `name` | string | yes | Device display name (e.g. "Bar Terminal 1"). |
| `authorities` | enum[] | yes | Permissions granted to this API key. |
| `organization` | object | yes | The organization the device belongs to. |
| `place` | object | yes | The venue (business unit) the device is assigned to. |
| `relatedDesks` | object[] | yes | Desks this device serves. |

---

## Authorities

The `authorities` array determines which operations the 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. |

Read `authorities` at startup and gate POS features on it. A key provisioned only for coupons
cannot process payments.

---

## Organization — `IntegrationOrganizationResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Organization id in the Cheers system. |
| `name` | string | yes | Organization name. **Printed on receipts.** |

## Place — `IntegrationPlaceResponse`

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

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Place id in the Cheers system. |
| `name` | string | yes | Place name. **Printed on receipts.** |
| `description` | string | no | Optional description of the place. |
| `formattedAddress` | string | yes | Full formatted address. |
| `avatarMedia` | object | no | Optional place image — see `MediaResponse` below. |
| `placeStatus` | enum | yes | Current status of the place. |

### Place statuses

| Status | Description |
|---|---|
| `DRAFT` | Not published yet. |
| `ACTIVE` | Live and operating. |
| `TEMPORARILY_CLOSED` | Closed for now, will reopen. |
| `PERMANENTLY_CLOSED` | Closed for good. |
| `HIDDEN` | Not visible to customers. |

### `MediaResponse` (`place.avatarMedia`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Media id. |
| `processingStatus` | enum | yes | `COMPLETE`, `ERROR`, `PROCESSING`, `QUEUED`. |
| `mediaType` | enum | yes | `IMAGE`, `VIDEO`, `PDF`. |
| `uris` | array | yes | One entry per available rendition. |

`uris[]` — `URIResponse`:

| Field | Type | Required | Description |
|---|---|---|---|
| `src` | string | yes | The asset URL. |
| `blurHash` | string | no | Placeholder hash for progressive loading. |
| `URIType` | enum | yes | Which rendition this is. |

`URIType` values: `LARGE`, `MEDIUM`, `SMALL`, `VIDEO_THUMBNAIL`, `VIDEO`, `VIDEO_HLS_INDEX`,
`VIDEO_HLS_INDEX_LOW`, `VIDEO_HLS_INDEX_MEDIUM`, `VIDEO_HLS_INDEX_HIGH`, `PDF`, `GIF`.

## Related desks — `IntegrationDeskResponse`

The desks this device serves. Same shape as the desks returned by the Counter Order desk
endpoints (`GET /v1/integrations/me/desks`).

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

This endpoint **reports** desk state but does not change it. To suspend or resume ordering, use
`PUT /v1/integrations/desks/status` from the Counter Order API.

---

## Error handling

Standard error envelope:

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

| Status | Meaning |
|---|---|
| `400` | Malformed request. |
| `401` | Missing or invalid `X-API-Key`. |
| `403` | 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.