API reference

Devices

REST endpoints for managing fiscal devices (AMEFs) — CRUD, claim/release, live status, alerts, and the full set of device commands (cash balance, datetime, logos, VAT rates, header/footer, operators, void, reversal, etc.).

Devices

The Devices API is the largest surface in e-bon. It splits into two layers, both mounted under /api/v1/devices:

CRUD & introspection — register, update and delete devices, list them, fetch status and alerts. These endpoints read and write the Firestore device record and the in-memory WebSocket gateway.
Commands & live operations — claim/release control of a device, dispatch fiscal commands (set_datetime, print_duplicate, non_fiscal_receipt, set_logo, VAT/header/footer/operator configuration, voiding, reversals…), and fetch live data from the device. For most command routes, the platform forwards the request to the device over WebSocket and waits for the device's reply before responding.

Each endpoint declares its own scope below. The four scopes used in this group are devices:read, devices:write, commands and receipts — see Authentication › Choose scopes for the full catalogue. The error envelope, rate limits and authentication rules are documented once on API overview.

Live-command endpoints (cash balance, set datetime, print duplicate, non-fiscal, logo, VAT rates, header/footer, operator, info, last-receipt, void, reversal) require the device to be online over WebSocket and to have an assigned controller. If either condition is not met, the request fails with 503 SERVICE_UNAVAILABLE.

CRUD

POST /api/v1/devices

Registers a new fiscal device on the organization.

Auth scope: devices:write
Tier check: the request is checked against your plan's device limit before the body is validated; if your organization is already at its device limit, the request is rejected with 403.

Request body

Field	Type	Required	Notes
`name`	string	yes	1–255 chars.
`protocol`	string	yes	One of `datecs_compact`, `datecs_professional`, `datecs_extended`, `daisy`, `daisy_ro`, `eltrade`, `incotex`, `tremol`, `tremol_v2`, `custom`, `mfje`.
`transport`	string	yes	One of `tcp`, `bluetooth`, `serial`, `usb`.
`locationId`	string	yes	The location the device belongs to (≥ 1 char).
`connectionParams`	object	yes	Either `{ host: string, port: number (1–65535) }` (TCP) or `{ address: string }` (bluetooth/serial/usb).

Response (`201 Created`)

{
  "id": "dev_pos_01",
  "name": "Tejghea POS 1",
  "protocol": "datecs_compact",
  "transport": "tcp",
  "locationId": "loc_main",
  "connectionParams": { "host": "192.168.1.50", "port": 9100 },
  "orgId": "acme_corp",
  "status": "offline",
  "controllerId": null,
  "controllerName": null,
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:00.000Z"
}

Example

curl -X POST https://api.e-bon.ro/api/v1/devices \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tejghea POS 1",
    "protocol": "datecs_compact",
    "transport": "tcp",
    "locationId": "loc_main",
    "connectionParams": { "host": "192.168.1.50", "port": 9100 }
  }'

Parameter	Type	Notes
`status`	string	One of `online`, `offline`, `busy`, `error`.
`locationId`	string	Filter by location.

Field	Type	Required	Notes
`type`	string	yes	One of: `print_receipt`, `void_receipt`, `x_report`, `z_report`, `cash_in`, `cash_out`, `get_status`, `get_cash_amount`, `set_datetime`, `print_duplicate`, `non_fiscal_receipt`, `set_logo`, `delete_logo`, `raw_command`, `open_drawer` (and the more specific types listed in the dedicated routes below).
`payload`	object	yes	Command-specific payload. Pre-validated server-side.

Field	Type	Required	Notes
`lines`	string	yes	At least one line. Each line ≤ 48 chars.
`header`	string	no	Optional header text printed bold/centered at the top. ≤ 48 chars.

Parameter	Type	Default	Notes
`type`	string	—	Filter by receipt type (`sale` / `refund` / `storno`).
`limit`	integer	`50`	`1`–`100`.