printers`

Endpoint: GET /api/printers
Auth Scope: Profile Protected (verify_operational_profile_access)
Target Service: Local DaemonX Bridge Daemon (127.0.0.1:9123)
Introduced In: v1.0.0
Last Updated: v1.0.0

1. Description & Purpose

GET /api/printers queries the host machine's Windows Print Spooler (Win32_Printer) and returns an inventory of all currently installed printer devices, their associated driver names, assigned hardware ports (e.g. USB001, COM1, or IP socket ports), online readiness status, and default printer flag.

Web POS applications use this endpoint in Hardware / Register Settings to populate printer selection dropdowns for:

Thermal Receipt Printers (e.g., Epson TM-T82, Star TSP100, Rongta, Xprinter)
Kitchen Order Printers (KOT)
Full-page A4 / Letter Invoice Printers (Epson L-series, HP LaserJet, Canon)

2. Authentication & Required Headers

This endpoint requires counter credentials and verifies caller origin. It also enforces the operational offline gate (blocked with HTTP 403 if the workstation is offline and its emergency print allowance is exhausted).

Header Name	Type	Required	Description	Example
`Accept`	`string`	No	`application/json`	`application/json`
`Origin`	`string`	Yes	Web POS browser origin. Must match counter's `allowed_origins`.	`https://pos.yourdomain.com`
`X-Bridge-Counter-Id`	`string` (UUID)	Yes	Counter ID registered in local DaemonX profile store.	`d402ddec-ecf7-4b39-b57a-86ce6008df05`
`X-Bridge-Profile-Secret`	`string`	Yes	Counter profile secret issued during pairing (`dxp_...`).	`dxp_202b541b2a72ecc32867e0f62b26b...`

3. TypeScript Contracts

export interface PrinterInfo {
  name: string;
  driver_name: string;
  port_name: string;
  status: 'Ready' | string;
  is_default: boolean;
}

export interface DaemonXPrintersResponse {
  success: boolean;
  counter_id: string;
  printers: PrinterInfo[];
}

export interface DaemonXErrorResponse {
  detail: {
    error: string;
    message: string;
    counter_id?: string;
    offline_remaining?: number;
    reconnect_required?: boolean;
    gate_reason?: string;
    operation?: string;
  };
}

4. Response Field Matrix

Field	Type	Description
`success`	`boolean`	`true` when query succeeds.
`counter_id`	`string`	UUID of the authenticated counter profile.
`printers`	`PrinterInfo[]`	Array of installed Windows printer devices.
`printers[].name`	`string`	Exact Windows printer name. Pass this string to `/api/print/*` endpoints.
`printers[].driver_name`	`string`	Windows driver model (e.g. `"EPSON Advanced Printer Driver 6"`).
`printers[].port_name`	`string`	Windows hardware port (e.g. `"USB001"`, `"192.168.1.100"`, `"COM3"`).
`printers[].status`	`string`	`"Ready"` if online and ready to accept print spooler payloads.
`printers[].is_default`	`boolean`	`true` if this printer is configured as the Windows default device.

5. Real-World Response Examples

Example A: Successful Query (200 OK)

{
  "success": true,
  "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
  "printers": [
    {
      "name": "EPSON TM-T82III Receipt",
      "driver_name": "EPSON Advanced Printer Driver 6",
      "port_name": "USB001",
      "status": "Ready",
      "is_default": true
    },
    {
      "name": "EPSON L130 Series",
      "driver_name": "EPSON L130 Series",
      "port_name": "USB002",
      "status": "Ready",
      "is_default": false
    },
    {
      "name": "Microsoft Print to PDF",
      "driver_name": "Microsoft Print To PDF",
      "port_name": "PORTPROMPT:",
      "status": "Ready",
      "is_default": false
    }
  ]
}

Example B: Operational Lockout (403 Forbidden)

Returned when the workstation has been disconnected from Core and has exhausted all 30 emergency offline prints:

{
  "detail": {
    "error": "DAEMONX_OFFLINE_ALLOWANCE_EXHAUSTED",
    "message": "Emergency offline allowance exhausted. Reconnect this counter to continue.",
    "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
    "offline_remaining": 0,
    "reconnect_required": true,
    "gate_reason": "OFFLINE_ALLOWANCE_EXHAUSTED",
    "operation": "profile_operation"
  }
}

6. Integration Snippets

cURL

curl -X GET "http://127.0.0.1:9123/api/printers" \
  -H "X-Bridge-Counter-Id: d402ddec-ecf7-4b39-b57a-86ce6008df05" \
  -H "X-Bridge-Profile-Secret: dxp_202b541b2a72ecc32867e0f62b26b07be38024210e30af90" \
  -H "Origin: https://pos.yourdomain.com"

TypeScript Client Function

export async function getInstalledPrinters(
  counterId: string,
  profileSecret: string
): Promise<PrinterInfo[]> {
  const res = await fetch('http://127.0.0.1:9123/api/printers', {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'X-Bridge-Counter-Id': counterId,
      'X-Bridge-Profile-Secret': profileSecret,
    },
  });

  if (!res.ok) {
    const errorData = await res.json().catch(() => null);
    if (res.status === 403 && errorData?.detail?.reconnect_required) {
      throw new Error('OFFLINE_LOCKED: Please reconnect terminal to internet.');
    }
    throw new Error(errorData?.detail?.message || `Failed to fetch printers (HTTP ${res.status})`);
  }

  const data: DaemonXPrintersResponse = await res.json();
  return data.printers;
}

List Printers