TypeScript SDK

client.devices

Reference for client.devices — every method with TypeScript signatures, parameters and Node examples, mirroring the /api/v1/devices REST surface.

`client.devices`

client.devices wraps /api/v1/devices/* — fiscal-device CRUD, live status and connection history, header/footer/VAT/operator configuration, on-device receipt printing helpers, alerts and the claim/release flow used by the E-BON mobile app. Every method returns the same plain object shape as the matching REST endpoint documented in Devices API.

All HTTP-level failures surface as EBonApiError — see Errors and the cross-referenced HTTP error catalogue at /en/api/errors.

`client.devices.list(query?)`

List all devices, optionally filtered by status or locationId.

async list(query?: ListDevicesQuery): Promise<Device[]>

Name	Type	Required	Notes
`status`	`string`	no	One of `online`, `offline`, `error` — see `DeviceStatus` in `@e-bon/types`.
`locationId`	`string`	no	Filter to a single location.

Returns an array of Device objects.

const onlineTills = await client.devices.list({ status: 'online' });
console.log(onlineTills.map((d) => d.id));

`client.devices.get(id)`

Get a single device by ID.

async get(id: string): Promise<Device>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns a single Device.

const device = await client.devices.get('dev_01HZ...');

`client.devices.create(body)`

Register a new fiscal device.

async create(body: CreateDeviceBody): Promise<Device>

Name	Type	Required	Notes
`name`	`string`	yes	Human-readable label.
`protocol`	`DeviceProtocol`	yes	Wire protocol — see `@e-bon/types`.
`transport`	`DeviceTransport`	yes	`tcp`, `bluetooth`, `usb`, etc.
`connectionParams`	`ConnectionParams`	yes	Protocol-specific connection details.
`locationId`	`string`	no	Optional location to assign.

Returns the created Device.

const device = await client.devices.create({
  name: 'Counter 1',
  protocol: 'datecs_dp25',
  transport: 'tcp',
  connectionParams: { host: '10.0.0.20', port: 4001 },
});

`client.devices.update(id, body)`

Update device properties.

async update(id: string, body: UpdateDeviceBody): Promise<Device>

Name	Type	Required	Notes
`name`	`string`	no	Rename the device.
`connectionParams`	`ConnectionParams`	no	Replace the full connection params object.
`locationId`	`string \| null`	no	Move to a location, or `null` to detach.

Returns the updated Device.

await client.devices.update('dev_01HZ...', { name: 'Counter A' });

`client.devices.delete(id)`

Delete a device.

async delete(id: string): Promise<undefined>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns undefined on success.

await client.devices.delete('dev_01HZ...');

`client.devices.getStatuses()`

Get batch device statuses.

async getStatuses(): Promise<DeviceStatusesResult>

No parameters. Returns { statuses: Record<deviceId, DeviceStatusInfo> }.

const { statuses } = await client.devices.getStatuses();

`client.devices.getStatus(id)`

Get device connection status.

async getStatus(id: string): Promise<DeviceStatusInfo>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns a single DeviceStatusInfo.

const status = await client.devices.getStatus('dev_01HZ...');

`client.devices.getConnectionHistory(id)`

Get device connection history.

async getConnectionHistory(id: string): Promise<ConnectionHistoryResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { events: ConnectionEvent[] } with chronological connect/disconnect entries.

const { events } = await client.devices.getConnectionHistory('dev_01HZ...');

`client.devices.sendCommand(id, body)`

Submit a command to a specific device.

async sendCommand(id: string, body: SendDeviceCommandBody): Promise<FiscalCommand>

Name	Type	Required	Notes
`type`	`CommandType`	yes	Command kind — see `@e-bon/types`.
`payload`	`unknown`	no	Command-specific payload (shape depends on `type`).

Returns the created FiscalCommand record (status starts as pending). Subscribe to the events WebSocket for command.completed / command.failed.

const cmd = await client.devices.sendCommand('dev_01HZ...', {
  type: 'print_x_report',
});

`client.devices.getReceipts(id, query?)`

List receipts for a specific device.

async getReceipts(id: string, query?: ListDeviceReceiptsQuery): Promise<Receipt[]>

Name	Type	Required	Notes
`type`	`string`	no	Receipt type filter — see `ReceiptType`.
`startDate`	`string`	no	ISO-8601 lower bound (inclusive).
`endDate`	`string`	no	ISO-8601 upper bound (inclusive).
`limit`	`number`	no	Page size; server caps the maximum.
`startAfter`	`string`	no	Cursor — pass the previous page's last receipt ID.

Returns an array of Receipt. (The SDK unwraps the { receipts } envelope.)

const recent = await client.devices.getReceipts('dev_01HZ...', { limit: 50 });

`client.devices.getCashBalance(id)`

Get cash balance for a device.

async getCashBalance(id: string): Promise<CashBalanceResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { cashBalance, currency, deviceId, timestamp }.

const { cashBalance } = await client.devices.getCashBalance('dev_01HZ...');

`client.devices.setDatetime(id, body)`

Set device date/time.

async setDatetime(id: string, body: SetDatetimeBody): Promise<undefined>

Name	Type	Required	Notes
`datetime`	`string`	yes	ISO-8601 datetime to push to the device clock.

Returns undefined on success.

await client.devices.setDatetime('dev_01HZ...', { datetime: new Date().toISOString() });

`client.devices.printDuplicate(id)`

Print duplicate of last receipt.

async printDuplicate(id: string): Promise<undefined>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns undefined on success.

await client.devices.printDuplicate('dev_01HZ...');

`client.devices.nonFiscalReceipt(id, body)`

Print a non-fiscal text receipt.

async nonFiscalReceipt(id: string, body: NonFiscalReceiptBody): Promise<undefined>

Name	Type	Required	Notes
`lines`	`string[]`	yes	One entry per printed line.
`header`	`string`	no	Optional header line printed first.

Returns undefined on success.

await client.devices.nonFiscalReceipt('dev_01HZ...', {
  lines: ['Welcome', 'See you soon'],
});

`client.devices.uploadLogo(id, body)`

Upload logo to device.

async uploadLogo(id: string, body: UploadLogoBody): Promise<undefined>

Name	Type	Required	Notes
`logo`	`string`	yes	Base64-encoded bitmap (driver-specific).

Returns undefined on success.

await client.devices.uploadLogo('dev_01HZ...', { logo: base64Bitmap });

`client.devices.deleteLogo(id)`

Delete logo from device.

async deleteLogo(id: string): Promise<undefined>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns undefined on success.

await client.devices.deleteLogo('dev_01HZ...');

`client.devices.getVatRates(id)`

Get VAT rates configured on a device.

async getVatRates(id: string): Promise<VatRatesResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { rates: VatRate[], deviceId, timestamp }.

const { rates } = await client.devices.getVatRates('dev_01HZ...');

`client.devices.getVatCapabilities(id)`

Get VAT capabilities of a device.

async getVatCapabilities(id: string): Promise<VatCapabilitiesResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { capabilities, deviceId, timestamp } describing what the printer firmware accepts.

const caps = await client.devices.getVatCapabilities('dev_01HZ...');

`client.devices.setVatRates(id, body)`

Set VAT rates on a device.

async setVatRates(id: string, body: SetVatRatesBody): Promise<undefined>

Name	Type	Required	Notes
`rates`	`VatRate[]`	yes	Array of `{ name, percentage }` entries.

Returns undefined on success.

await client.devices.setVatRates('dev_01HZ...', {
  rates: [
    { name: 'A', percentage: 19 },
    { name: 'B', percentage: 9 },
  ],
});

`client.devices.getHeaderFooterCapabilities(id)`

Get header/footer capabilities of a device.

async getHeaderFooterCapabilities(id: string): Promise<HeaderFooterCapabilitiesResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { capabilities: { maxHeaderLines, maxFooterLines, maxCharsPerLine }, deviceId, timestamp }.

const caps = await client.devices.getHeaderFooterCapabilities('dev_01HZ...');

`client.devices.getHeaderFooter(id)`

Get header and footer lines configured on a device.

async getHeaderFooter(id: string): Promise<HeaderFooterResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { header: string[], footer: string[], deviceId, timestamp }.

const { header, footer } = await client.devices.getHeaderFooter('dev_01HZ...');

`client.devices.setHeaderFooter(id, body)`

Set header and footer lines on a device.

async setHeaderFooter(id: string, body: SetHeaderFooterBody): Promise<undefined>

Name	Type	Required	Notes
`header`	`string[]`	yes	Header lines (respect `maxHeaderLines`).
`footer`	`string[]`	yes	Footer lines (respect `maxFooterLines`).

Returns undefined on success.

await client.devices.setHeaderFooter('dev_01HZ...', {
  header: ['ACME SRL', 'CUI RO12345678'],
  footer: ['Mulțumim!'],
});

`client.devices.getOperatorCapabilities(id)`

Get operator capabilities for a device.

async getOperatorCapabilities(id: string): Promise<OperatorCapabilitiesResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { capabilities: { maxOperators, maxNameLength, maxPasswordLength, supportsPassword }, deviceId, timestamp }.

const caps = await client.devices.getOperatorCapabilities('dev_01HZ...');

`client.devices.setOperator(id, body)`

Set operator name/password on a device.

async setOperator(id: string, body: SetOperatorBody): Promise<undefined>

Name	Type	Required	Notes
`operatorId`	`number`	yes	Slot index — bounded by `maxOperators`.
`name`	`string`	yes	Operator display name.
`password`	`string`	no	Required only when the device `supportsPassword`.

Returns undefined on success.

await client.devices.setOperator('dev_01HZ...', { operatorId: 1, name: 'Ana' });

`client.devices.getInfo(id)`

Get live device info (serial, firmware, fiscal memory, manufacturer).

async getInfo(id: string): Promise<DeviceInfoResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { serialNumber, firmwareVersion, fiscalMemoryStatus, manufacturer, model? }.

const info = await client.devices.getInfo('dev_01HZ...');

`client.devices.getLastReceiptInfo(id)`

Get last receipt info from a device.

async getLastReceiptInfo(id: string): Promise<LastReceiptInfoResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { receiptNumber, date, total, fiscalMemoryNumber?, deviceId, timestamp }.

const last = await client.devices.getLastReceiptInfo('dev_01HZ...');

`client.devices.voidOpenReceipt(id)`

Void an open receipt on a device.

async voidOpenReceipt(id: string): Promise<VoidOpenReceiptResult>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns { success, message, deviceId, timestamp }.

const res = await client.devices.voidOpenReceipt('dev_01HZ...');

`client.devices.printReversalReceipt(id, body)`

Print a reversal receipt on a device.

async printReversalReceipt(id: string, body: ReversalReceiptBody): Promise<ReversalReceiptResult>

Name	Type	Required	Notes
`uniqueSaleNumber`	`string`	yes	Sale identifier on the original receipt.
`originalReceiptNumber`	`string`	yes	Original receipt number.
`originalReceiptDateTime`	`string`	yes	ISO-8601 timestamp of the original receipt.
`fiscalMemorySerialNumber`	`string`	yes	Serial number of the original device's fiscal memory.
`originalZReportNumber`	`string`	no	Z report number containing the original receipt.
`reason`	`'operator_error' \| 'refund' \| 'tax_base_reduction'`	yes	Legal reason code.
`items`	`ReversalReceiptItem[]`	yes	Items to reverse — `{ name, quantity, price, vatRate }`.
`payments`	`ReversalReceiptPayment[]`	no	Optional refund payment lines.

Returns { success, message, receiptNumber?, deviceId, timestamp }.

await client.devices.printReversalReceipt('dev_01HZ...', {
  uniqueSaleNumber: 'SALE-1042',
  originalReceiptNumber: '0001234',
  originalReceiptDateTime: '2026-04-20T11:32:00+03:00',
  fiscalMemorySerialNumber: 'DY12345678',
  reason: 'refund',
  items: [{ name: 'T-shirt', quantity: 1, price: 49.9, vatRate: 19 }],
});

`client.devices.getAlerts(id, query?)`

Get alerts for a specific device.

async getAlerts(id: string, query?: ListDeviceAlertsQuery): Promise<DeviceAlert[]>

Name	Type	Required	Notes
`severity`	`string`	no	Filter by `DeviceAlertSeverity`.

Returns an array of DeviceAlert. (The SDK unwraps the { alerts } envelope.)

const alerts = await client.devices.getAlerts('dev_01HZ...', { severity: 'error' });

`client.devices.getAllAlerts(query?)`

Get batch alerts for all org devices.

async getAllAlerts(query?: ListDeviceAlertsQuery): Promise<BatchAlertsResult>

Name	Type	Required	Notes
`severity`	`string`	no	Filter by `DeviceAlertSeverity`.

Returns { alerts: Record<deviceId, DeviceAlert[]> }.

const { alerts } = await client.devices.getAllAlerts();

`client.devices.claim(id, body)`

Claim control of a device.

async claim(id: string, body: ClaimDeviceBody): Promise<undefined>

Name	Type	Required	Notes
`appInstanceId`	`string`	yes	The mobile-app instance taking control.

Returns undefined on success.

await client.devices.claim('dev_01HZ...', { appInstanceId: 'app_inst_01HZ...' });

`client.devices.release(id)`

Release control of a device.

async release(id: string): Promise<undefined>

Name	Type	Required	Notes
`id`	`string`	yes	Device identifier.

Returns undefined on success.

await client.devices.release('dev_01HZ...');

Edit this page

Errors

The FiscalError and EBonApiError exception classes, the ErrorCode enum and RETRYABLE_ERRORS set re-exported from @e-bon/sdk, and a recommended retry pattern.

client.commands

Reference for the CommandsResource — submit fiscal commands asynchronously, list, poll a single command and cancel a pending one, mirroring /api/v1/commands.