## Connect a device to a terminal

Connect a device to a terminal instance. If the terminal has no device bound,
this will bind the provided `device_id` and generate a fresh API key token
(prefixed with `reservepay_`). If the terminal is already bound to the same
`device_id`, the previous key is revoked and a new one is issued.

If the terminal is bound to a different device, an `ALREADY_CONNECTED` error
is returned.

If the terminal is disabled, `NOT_ENABLED` is returned.

If the terminal has no installation linked, `NOT_CONFIGURED` is returned.

## Endpoint signature

```http
POST https://api.reservepay.com/terminals/connect-device HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  merchant_id: string,
  terminal_id: string,
  device_id: string,
  challenge: string?,
}
```

Returns: string

## Request arguments

### `merchant_id` (string)

**Required**. The merchant ID this terminal belongs to.

### `terminal_id` (string)

**Required**. Terminal ID the device is connected to.

### `device_id` (string)

**Required**. Device UUID generated on device.

### `challenge` (string)

_Optional_. One-time challenge from the terminal QR code. Validated if provided; required when server enforces challenge mode.

## Errors specific to this endpoint

### `ALREADY_CONNECTED`

The terminal is connected to another device.

### `INVALID_CHALLENGE`

The challenge is missing or does not match the terminal's current challenge.

### `NOT_FOUND`

Merchant or terminal could not be found.

### `NOT_ENABLED`

The terminal exists but is disabled; enable it before connecting a device.

### `NOT_CONFIGURED`

The terminal has no installation linked; assign an installation first.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

Raised when the server encounters an unexpected internal error.

### `INVALID_ARGUMENTS`

Raised when the request contains invalid or missing parameters.

### `BAD_VERSION`

Raised when requesting an unsupported or deprecated API version.