# Terminals

Payment terminal management

## GET /api/v1/terminals

List payment terminals

Get all payment terminals for a location

**Permissions:** 🔵 `terminals.read`

Query parameters:
- `locationId` (string, required) — Location ID to fetch terminals for

Response 200 — Terminals fetched successfully

```ts
{
  status?: "success"
  data?: Array<{
      id: string // uuid
      externalId: string
      locationId: integer
      createdAt: string // date-time
      updatedAt: string // date-time
      title: string
      type: "p400plus" | "s1f2" | "s1u2" | "s1e2l" | "v400cplus" | "v400m" | "any" | null
      status?: "idle" | "busy" | "error"
      statusDetails?: string[]
      statusError?: string
      probeId?: string // uuid
      checkedAt?: string // date-time
    }>
  meta?: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/terminals/status-diagnostics

Record a POS terminal status delivery anomaly

Request body:

```ts
{
  outcome: "http_fallback" | "status_timeout" | "http_error" | "stale_event" | "terminal_not_found"
  surface: "quick_pay" | "pay_drawer"
  terminalIds: string[]
  probeIds?: string[]
  connectionState?: string
  durationMs?: number
  clientLocationId?: integer
}
```

Response 202 — Default Response

```ts
{
  status: "success"
  data: {
    accepted: boolean
  }
  meta?: Record<string, unknown>
}
```

## GET /api/v1/terminals/statuses

Get terminal statuses

Request real-time connection status for all terminals at a location, or one terminal

**Permissions:** 🔵 `terminals.read`

Query parameters:
- `locationId` (string, required) — Location ID to fetch terminal statuses for
- `terminalId` (string, optional) — Optional terminal ID to check only that terminal
- `terminalIds` (string, optional) — Comma-separated IDs of up to four Quick Pay terminals
- `waitForStatus` ("true" | "false", optional) — Wait for probe results and include them in the response

Response 200 — Terminal statuses fetched successfully

```ts
{
  status?: "success"
  data?: {
    terminals: Array<{
        id: string // uuid
        externalId: string
        locationId: integer
        createdAt: string // date-time
        updatedAt: string // date-time
        title: string
        type: …
        status?: "idle" | "busy" | "error"
        statusDetails?: unknown[]
        statusError?: string
        probeId?: string // uuid
        checkedAt?: string // date-time
      }>
    message: string
  }
  meta?: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```