MiniPOS Invoice API

🧾 Invoice API

This API allows you to create a new sales or refund invoice, which can optionally be printed as a paper receipt. It supports full customization of line items, customer data, discounts, and additional printed elements like text blocks or barcodes.

📦 Request Structure Overview

The request body is a JSON object that consists of the following main parts:

Top-level fields: General invoice data (e.g. mode, POS ID, discounts, printing options)

info: Optional metadata such as header/footer content and customer contact info

rows: A list of items/products added to the invoice

payments: Optional list of payment methods and amounts

📥 Request Fields

🔹 Top-Level Fields

invoice_no (string): Unique identifier for the invoice (e.g. "XXX-01-257").

mode (int): Type of invoice.

1 = Sale

2 = Refund

3 = Non fiscal slip

pos_id (int or null): Optional. Limits visibility to a specific POS station. If null, the invoice is visible to all POS devices in the same station group.

discount (float): Optional invoice-wide discount.

discount_type (string): "amount" or "percent" — determines how the top-level discount is applied.

comment (string): Optional comment saved with the invoice.

print_paper_receipt (bool or null): If null, defaults to printing. Set to false to suppress printing.

keep_drawer_closed (bool): Controls the cash drawer. true = drawer remains closed.

is_auto_open (bool): If true, the invoice will automatically open on the POS (if idle) and non fiscal slip will automatically print.

🧾 info Section

header / footer: Optional array of printed elements at the top/bottom of the receipt. Each element can be:

Text block: kind = "text", content = "Your message here"

Barcode block: kind = "barcode", code = "1234567890123", type = 2, align = 1, height = 40, width = 2, text_position = 2

customer: Optional customer contact info metadata for internal/external processing, for example: sending electronic receipts

phone: "+37199999999"

email: "user@domain.com"

🧾 Barcode Format Reference

(These parameters translate directly into hardware-level ESC/POS commands for the printer)

type: Defines the barcode symbology to be used. Ensure your code string matches the character and length requirements for the chosen standard.

0 - UPC-A

1 - UPC-E

2 - EAN13

3 - EAN8

4 - CODE39

5 - ITF

6 - CODEBAR

72 - CODE93

73 - CODE128

101 - QR CODE

align: Controls the horizontal alignment of the barcode on the receipt roll.
0 = Left, 1 = Center, 2 = Right

width: Controls the horizontal thickness (module width) of the barcode lines.
0 = Use printer's internal default.
X = Custom thickness. For standard ESC/POS printers, valid values typically range from 2 (thinnest) to 6 (thickest). If your barcode fails to scan, try increasing the width.

height: Controls the vertical height of the barcode lines measured in printer dots.
0 = Use printer's internal default (often around 162 dots).
X = Custom height. Valid values typically range from 1 to 255. Values between 40 and 80 generally produce a standard, well-proportioned receipt barcode.

text_position: Determines where the Human Readable Interpretation (HRI) text (the actual numbers/letters of the code) will print.
0 = Do not print text, 1 = Print Above, 2 = Print Below, 3 = Print Both Above and Below

rec_place (optional): Determines the printing phase or location block on the receipt.
0 = Current position, 1 = Receipt top, 2 = Receipt middle, 3 = Receipt end

Payload Example: Printing a Standard CODE128 Barcode
This request generates a perfectly centered barcode with custom physical dimensions, placing the human-readable text directly beneath the bars:

{  
    "kind": "barcode",  
    "code": "68999870038580428",  
    "type": 73,  
    "align": 1,  
    "height": 40,  
    "width": 2,  
    "text_position": 2  
}

🧾 Mode 3 Non fiscal slip only commands

escpos: Command is only for nonfiscal slip (mode 3) and it can send in any escpos command that is supported and whitelisted by fiscal libary to the printer to format the text.

text: Text line should not be wider than the maximum character width of the printer connected to the fiscal device. Usually 40, 42, or 48 characters, including spaces.

📦 rows Section

An array of line items in the invoice.

Each item supports the following fields:

code (string): Internal product code

text (string): Product name or description

quantity (float): Number of units (or weight, if is_weight = true)

price (float): Price per unit, before discounts or tax

discount (float): Optional item-level discount

discount_type (string): "percent" or "amount"

tax (int or null): Tax group ID. If null, a default will be applied.

fiscal_section (int or null): POS grouping/counter ID. If null, a default will be used.

is_free_price (bool): Allows manual price entry at the POS

is_weight (bool): Interprets quantity as weight or volume

payload (string): Free-form custom data for internal/integrator use

info.blocks (array): Text or barcode blocks printed below the item

🧮 Price and Quantity Format

price: Float with up to 2 decimal places (e.g. 2.34)

quantity: Float with up to 3 decimal places (e.g. 0.001) — suitable for precise weights or measurements

ℹ️ Note: If tax or fiscal_section is null, the system will apply default values based on the POS configuration.

💳 payments Section

An optional array of payments applied to the invoice.

method_id (int): Payment method ID

Example: 0 = Cash, 1 = Credit Card (configurable)

amount (float or null):

If provided: defines the exact amount paid

If null: system assigns the remaining balance to this method

method_name (string):

If custom method_name is needed on the receipt

💡 Partial payments are supported. Operators can manually complete payment at the POS using additional methods.

📤 Response

A successful response returns the full invoice object, including metadata, items, and payments. Example fields:

id: Internal invoice ID

invoice_no: Invoice number

mode: 1 (sale), 2 (refund) or 3 (non fiscal)

status: Status code

total_sum: Calculated invoice total

printed_at: Timestamp of printing (if printed)

rows: List of item rows

payments: List of payment entries

🧾 Invoice API#

📦 Request Structure Overview#

📥 Request Fields#

🔹 Top-Level Fields#

🧾 info Section#

🧾 Barcode Format Reference#

🧾 Mode 3 Non fiscal slip only commands#

📦 rows Section#

🧮 Price and Quantity Format#

💳 payments Section#

📤 Response#