API reference

Postman collection

Import the official e-bon Postman collection — 77+ pre-wired requests across 12 folders covering every public REST endpoint of the e-bon API.

Postman collection

Postman is an HTTP client for designing, testing and sharing API requests. The e-bon Postman collection is the same set of requests we use internally to smoke-test the API and onboard new POS partners — every public endpoint of api.e-bon.ro is included, organized by resource, with placeholders for the API key, JWT, base URL and a sample device id. Drop your credentials into the collection variables once and you can call the entire API surface from Postman without writing a line of code.

The collection is the fastest way to:

Explore the API interactively before committing to an SDK or hand-rolled HTTP client.
Reproduce a bug ticket against staging or production with the exact same request shape.
Hand a working set of requests to a junior dev so they can poke at the API without reading every reference page first.

See what's inside

The collection contains 77 requests grouped into 12 top-level folders, mirroring the resource pages in this section of the docs:

Health — 2 requests
Auth — 5 requests
Organization — 8 requests
API Keys — 5 requests
Devices — 24 requests
Fiscal Operations — 6 requests
Commands — 4 requests
Receipts — 2 requests
Reports — 10 requests
Billing — 6 requests
Users — 4 requests
App Instances — 1 request

Folder counts are sourced directly from the collection JSON; if a number above looks off, the JSON in the repository is the source of truth.

Import the collection

Download the collection

Grab the latest JSON from /e-bon-api.postman_collection.json (or the absolute URL https://docs.e-bon.ro/e-bon-api.postman_collection.json). The file is a Postman Collection v2.1.0 document and is small enough to fit in any browser download.

Open Postman

Launch the Postman desktop app or the web client at https://web.postman.co. Sign in with your workspace account if you want the collection to sync across devices.

Click Import

The Import button sits at the top-left of the sidebar, next to My Workspace. It opens the import modal.

Drop the JSON file

Drag e-bon-api.postman_collection.json into the modal (or click Choose files and select it). Postman parses the file and previews it as e-bon API.

Confirm the import

Click Import. The collection appears in your sidebar with all 12 folders expanded one level. Click any request to inspect its method, URL and pre-filled headers.

Configure variables

The collection ships with four variables that every request references via {{variable}} placeholders. Set them once at the collection level and every request picks them up.

Variable	Default value	What it is
`baseUrl`	`http://localhost:3000`	The API host and port. Switch to `https://api.e-bon.ro` for production.
`apiKey`	(empty)	Your `ebon_live_…` or `ebon_test_…` API key. Sent as the `x-api-key` header.
`token`	(empty)	A short-lived JWT access token. Sent as `Authorization: Bearer …` for JWT-only routes.
`deviceId`	(empty)	A device id from your organization. Used by the Devices, Commands and Fiscal folders.

Two ready-to-use environment presets:

Production

Variable	Value
`baseUrl`	`https://api.e-bon.ro`
`apiKey`	`ebon_live_<orgId>_<32-hex>`
`token`	(JWT, only if calling `/auth/` routes)*

Local development

Variable	Value
`baseUrl`	`http://localhost:3000`
`apiKey`	`ebon_test_<orgId>_<32-hex>`
`token`	(JWT from `POST /auth/login`)

To obtain an apiKey and a token, follow the walkthrough on the Authentication page.

Authenticate your requests

The collection includes both authentication flows the API supports:

API key — most resource folders (Devices, Commands, Receipts, Reports, Billing) send x-api-key: {{apiKey}} and target the production routes you would call from a POS integration.
JWT Bearer — the Auth folder exercises POST /auth/register, POST /auth/login, POST /auth/refresh and POST /auth/logout. The login response writes its access token into {{token}} so subsequent JWT-only calls are auto-authenticated.

Pick whichever matches your scenario: a POS partner or back-office integration almost always wants the API-key flow; only use JWT when you are exercising the same endpoints the Portal UI uses on behalf of a signed-in human.

For the deeper background — key format, scopes, rotation, error envelope — see Authentication and the Portal walkthrough at API keys.

Send your first request

Start with Health → GET health. It hits GET {{baseUrl}}/health, requires no API key and no JWT, and returns a small JSON status body. If it returns 200 OK you have proven that:

Your baseUrl is reachable.
Postman can talk to the e-bon API from your network.
Nothing in your TLS / proxy / VPN setup is blocking the request.

Once Health passes, move to Auth → POST login (for JWT) or jump straight into Devices → GET devices with your apiKey filled in.

Troubleshoot common errors

401 UNAUTHORIZED — apiKey is empty, malformed, or the key has been revoked. Open the Variables tab on the collection and confirm the value is the full ebon_live_… / ebon_test_… string with no trailing whitespace. If it looks right, regenerate it in the Portal under API keys.401 TOKEN_EXPIRED — your JWT token has aged out (access tokens are short-lived). Re-run Auth → POST refresh or Auth → POST login to get a fresh one and try again.403 FORBIDDEN — the API key is valid but its scopes do not cover the endpoint you called. Check the Scopes table on the Authentication page and add the missing scope to the key in the Portal.Connection refused / timeout — when baseUrl points at http://localhost:3000 the request only works while the e-bon API is running locally (pnpm --filter @e-bon/api dev). Either start the server or switch baseUrl to https://api.e-bon.ro.

Download the collection

Download the collection — e-bon-api.postman_collection.json, Postman Collection v2.1.0.

Edit this page

Webhook events

Receive real-time notifications about fiscal events — receipts, commands, devices, and reports — over signed HTTPS callbacks.

Errors reference

Canonical catalogue of every error e-bon can return — HTTP-level codes from the API and FiscalError codes from the device — with per-code recovery steps.