`/sale`

Request body:

Field	Type	Required	Format / constraints
`documentID`	integer (int64)	No	Internal document id
`documentExtID`	string	No	External document id
`docTime`	string	No	`yyyy-MM-dd HH:mm:ss`
`docNumber`	string	No	External document number
`employeeName`	string	No	Cashier name
`employeeFirstName`	string	No	Used when `employeeName` is empty
`employeeLastName`	string	No	Used when `employeeName` is empty
`discount`	integer (int64)	No	Document-level discount amount
`discountPrc`	number (double)	No	Document-level discount percent
`discountName`	string	No	Document-level discount label
`items`	array of item objects	Yes	Must be non-empty
`payments`	object	No	Payment split object
`extraPayments`	array of extra payment objects	No	Additional payment entries; also splits one receipt between several payments of the same type — see §7.14
`extraParams`	object (string → string)	No	Extra fields stored on the document and passed to the fiscal core as-is
`tips`	integer (int64)	No	Fallback tips value for the cashless payment; `payments.tips` takes precedence
`genPreview`	boolean	No	If `true`, requests a fiscal receipt preview (see `preview_data` in the response)

documentExtID is schema-optional but strongly recommended for every request — it is the idempotency/retry key used to safely recover from timeouts and unknown-delivery states. Always generate and send a unique one from your system — see §12.1.

extraParams carries fields that only the country's fiscal core interprets — the cashbox stores them on the document and forwards them untouched, so no contract change is needed when a country starts requiring a new field. Keys are country-specific; extra_params is accepted as an alias. Client/customer data for a Ghana receipt, for example:

"extraParams": {
  "clientCategID": "2",
  "clientCategName": "Organization",
  "clientFiscalID": "C0001234567",
  "clientName": "ACME Ltd",
  "clientDocNum": "GHA-123456789-0",
  "clientPhone": "+233201234567",
  "remarks": "Delivery to the warehouse"
}

Values are trimmed; empty ones are dropped. Which of these a receipt shows or reports is the fiscal core's decision (an individual has no TIN, an organization no ID document).

Success response:

Field	Type	Required	Notes
`documentID`	integer (int64)	No	Internal document id
`fiscalID`	string	No	Fiscal document id
`fiscalNum`	string	No	Fiscal document number
`fiscalUrl`	string	No	Fiscal URL
`docTime`	string	No	`yyyy-MM-dd HH:mm:ss`
`printTime`	string	No	`yyyy-MM-dd HH:mm:ss`
`docStatus`	integer (int32)	No	See value map below
`rrn`	string	No	Card terminal RRN of the first card payment
`auth`	string	No	Authorization code of the first card payment
`cardNum`	string	No	Card number (masked) of the first card payment
`bankName`	string	No	Acquiring bank name of the first card payment
`binName`	string	No	Card issuing bank (by BIN) of the first card payment
`checkNum`	string	No	Terminal check number
`printError`	integer (int32)	No	Print error code
`totalPayments`	array of payment entries	No	Payment breakdown, one entry per payment — see §7.13 and §7.14
`currency_name`	string	No	Currency
`documentExtID`	string	No	External document id
`preview_data`	string	No	Receipt preview text; present only when `genPreview=true` was requested

Specific values:

docStatus: 0 = open, 1 = closed.

auth, checkNum and success-level printError remain declared optional response fields. Current success mappers leave them null, so they are normally omitted from serialized JSON. Print failures use error-response printError (see §8.1).