Architecture

Command payload validation

Validation rules e-bon applies to every command request before it reaches your fiscal device — VAT rates, payment types, reversal reasons, items-vs-payments balance, and the error response you get when a payload is rejected.

Isometric diagram of an emerald validation gateway inspecting a JSON payload before it flows into the e-bon middleware tablet and onward to the fiscal printer

Every command you send to the e-bon API is validated before it reaches the device. If the payload fails validation, the request is rejected with HTTP 400 and a structured list of field-level errors — no command is queued, no receipt is printed.

This page documents the rules so you can build payloads that pass on the first try.

Validate against Romanian fiscal constants

Three fixed value sets are enforced on receipt-related commands.

VAT groups

Item-level vatGroup must be one of the device's VAT groups:

Group	Use
`VAT1`..`VAT16`	VAT groups programmed on the device
`exempt`	Exempt items

The actual percent for each group is not validated against a fixed national list — it is resolved from the printer's own rate table, which e-bon reads live from the device (get_vat_rates / get_vat_capabilities). Rates are never hardcoded.

Any other value is rejected with:

vatGroup must be one of: VAT1..VAT16, exempt

Payment types

Each entry in payments[] must declare a type from this set:

Value	Meaning
`cash`	Cash payment
`card`	Card payment
`check`	Check payment
`credit`	Credit / store account
`coupons`	Coupons
`meal-vouchers`	Meal vouchers (tichete de masă)
`value-tickets`	Value tickets (bilete valorice)
`voucher`	Voucher (gift voucher etc.)
`modern-payment`	Modern payment (mobile / wallet)
`card-advance`	Card advance
`foreign-currency`	Foreign currency
`bank`	Bank transfer
`ext-coupons`	External coupons
`packaging`	Packaging
`internal-usage`	Internal usage
`damage`	Damage / loss
`reserved1`	Reserved 1
`reserved2`	Reserved 2
`other`	Any other accepted tender

Rejection message:

type must be one of: cash, card, check, credit, coupons, meal-vouchers, value-tickets, voucher, modern-payment, card-advance, foreign-currency, bank, ext-coupons, packaging, internal-usage, damage, reserved1, reserved2, other

Reversal reasons

When issuing a reversal receipt, reason must be one of:

Value	When to use
`operator-error`	Cashier mistake on the original receipt
`refund`	Customer returned goods or cancelled service
`tax-base-reduction`	Tax base correction (e.g. subsequent discount)

Rejection message:

reason must be one of: operator-error, refund, tax-base-reduction

Balance items against payments

For receipts that carry both items and payments, the totals must match:

sum(items[i].quantity * items[i].price)  ==  sum(payments[i].amount)

Both sides are rounded to 2 decimals. A drift of up to ±0.01 RON is tolerated to absorb floating-point rounding — it is not a discount allowance.

If the totals don't match, the request is rejected with a message like:

Payment total (99.99) does not match items total (100.00)

This rule applies to every print_receipt request. It also applies to print_reversal_receiptwhen you include payments — see the asymmetry note below.

Apply per-command-type rules

The following commands carry payloads that are validated field-by-field. Commands not listed here either take no payload or only require their shape to match the request body schema.

`print_receipt`

The most demanding payload. Combines item validation, payment validation, and the items-vs-payments balance check.

Field	Rule
`items`	Required array, non-empty.
`items[i].name`	Required, non-empty string.
`items[i].quantity`	Required, positive number (`> 0`).
`items[i].price`	Required number.
`items[i].vatGroup`	Required, must be a device VAT group (`VAT1`..`VAT16` or `exempt`).
`payments`	Required array, non-empty.
`payments[i].type`	Required, must be a valid payment type.
`payments[i].amount`	Required, positive number (`> 0`).
Items vs payments	Totals must match within ±0.01 RON.

`void_receipt`

Field	Rule
`receiptId`	Required, non-empty string.

`cash_in` / `cash_out`

Both commands share the same validator.

Field	Rule
`amount`	Required, positive number (`> 0`).
`description`	Optional; if provided, must be a string.

`set_datetime`

Field	Rule
`datetime`	Optional; if provided, must be an ISO-8601 string.

`non_fiscal_receipt`

Field	Rule
`lines`	Required array with at least one entry; every element must be a string.
`header`	Optional; if provided, must be a string.

`set_logo`

Field	Rule
`logo`	Required, non-empty string.

`set_vat_rates`

Field	Rule
`rates`	Required array with at least one entry.
`rates[i].group`	Required, non-empty string — a device VAT group (`VAT1`..`VAT16`).
`rates[i].rate`	Required, non-negative number (`>= 0`).
`rates[i].enabled`	Required boolean.

This command does not restrict rates to a fixed national set — it pushes an arbitrary rate set to the device. The device firmware enforces what it will accept. The rate table itself is always read live from the printer (get_vat_rates / get_vat_capabilities); rates are never hardcoded.

`set_header_footer`

Field	Rule
`header`	Required array of strings.
`footer`	Required array of strings.

Empty arrays are accepted.

`set_operator`

Field	Rule
`operatorId`	Required positive integer (`>= 1`).
`name`	Required, non-empty string.
`password`	Optional; if provided, must be a string.
`oldPassword`	Optional; if provided, must be a string. Required by devices reporting `passwordChangeRequiresOldPassword`.

`print_reversal_receipt`

Field	Rule
`uniqueSaleNumber`	Required, non-empty string.
`originalReceiptNumber`	Required, non-empty string.
`originalReceiptDateTime`	Required, must be a date string parsable as ISO-8601.
`fiscalMemorySerialNumber`	Required, non-empty string.
`originalZReportNumber`	Optional; if provided, must be a string.
`reason`	Required, must be a valid reversal reason.
`items`	Required array, non-empty (same per-item rules as `print_receipt`).
`payments`	Optional. If provided, every entry follows the same rules as `print_receipt`, and the items-vs-payments balance check applies.

`print_receipt` vs `print_reversal_receipt`

Items are required on both. Payments differ.

On print_receipt, payments is required.
On print_reversal_receipt, payments is optional — some reversals (for example, correcting a misprint that never collected money) carry no payment leg at all.

The items-vs-payments balance rule applies to both, but on a reversal it only runs when payments is present and non-empty.

Handle the validation error response

When a payload fails validation, the API returns HTTP 400 with this body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid command payload",
    "details": [
      { "field": "items[0].vatGroup", "message": "vatGroup must be one of: VAT1..VAT16, exempt" },
      { "field": "payments", "message": "Payment total (99.99) does not match items total (100.00)" }
    ]
  }
}

details lists every field that failed, in the order they were checked. To localise the error in your own UI, map on field + code rather than the message text — message strings are English-only and may evolve.

The dedicated reversal endpoint uses the same shape, but its top-level message is "Invalid reversal receipt payload" instead of "Invalid command payload".

Where to next

Reference: Command types — full payload shape catalogue per command type.
Reference: Error codes — full ErrorCode catalogue including VALIDATION_ERROR.
API: Commands — POST /api/v1/commands contract.
API: Devices — per-device command endpoints, including the reversal route.
API: Errors — wire shape of every error response.

Device alerts

Understand the five device alerts e-bon raises for your fiscal devices — paper low, cover open, fiscal memory almost full, Z report overdue, and disconnected — where they appear in the Portal, and how to consume them from the API.

How receipt emission works

Understand how e-bon dispatches a print command to your device, when it falls back to a push wakeup, how long each stage takes, and how you receive the final result.