Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hxmz-axfn07/qr-printing-sfw/llms.txt

Use this file to discover all available pages before exploring further.

Every print order passes through a defined sequence of statuses from the moment a customer submits it to the moment staff confirm the job is done. The admin dashboard exposes one action button per valid transition so staff can never accidentally skip a step or move an order backwards.

​
Order Status Lifecycle

Orders move forward through the following states. A failure or cancellation can interrupt the flow at specific points. 
new → reviewing → ready → printing → printed
                                    ↘ failed

(any active status) → cancelled
Active statuses — the set of statuses from which an order can still be cancelled — are: new, reviewing, ready, and printing.

​
Status Transitions

The table below maps each action the dashboard exposes to the status it requires and the status it produces. All transitions are enforced server-side in app.py; the dashboard button is simply disabled when the prerequisite status is not met.
ActionRequired statusResulting statusDashboard button
start_reviewnewreviewingStart Review
approvereviewingreadyApprove
start_printreadyprintingMark Printing
completeprintingprintedPrinted
failprintingfailedFailed (requires reason)
cancelany active statuscancelledCancel (requires reason)

​
Walking Through a Normal Order

1

New order arrives

A customer submits their files through the upload page. The order lands in the dashboard with status New and the stats counter increments immediately (the dashboard auto-refreshes every 3 seconds).
2

Start Review

A staff member clicks Start Review. The order moves to Reviewing. Staff can now open each uploaded file, check page counts, verify settings, and confirm the estimated cost.
3

Approve

Once satisfied, staff click Approve. The order moves to Ready and is queued for printing. If PRINT_COMMAND is configured, this is the status the server waits for before running the print job.
4

Mark Printing

Staff click Mark Printing. The order moves to Printing. If PRINT_COMMAND is set in .env, the server runs it automatically for each document at this point. See Printing for details.
5

Printed

Once the physical print job is finished and handed to the customer, staff click Printed. The order moves to Printed and the lifecycle is complete.

​
Searching Orders

The search box at the top of the dashboard performs a live search across three fields simultaneously:
  • Order ID — paste the UUID the customer received on the success page
  • Customer name — partial match, case-insensitive
  • Phone number — partial match
Use the status dropdown alongside search to narrow results to a specific stage of the workflow. Both controls take effect immediately — there is no submit button.

​
Viewing Documents

Each order card lists every file the customer uploaded. Click the document name to open the file directly in a new browser tab. The link is served by the server at: 
/files/<doc_id>?token=<admin_token>
The admin token is automatically appended by the dashboard. The ?token= query parameter authenticates the file request server-side, so files are never accessible without a valid token. Each document entry shows:
  • Original filename (linked)
  • File size
  • Page count (auto-detected for PDFs; ? if unknown)
  • Color mode (B/W or Color)
  • Print style (Single side or Double side)
  • Paper size
  • Number of copies
  • Estimated cost per document

​
Cancelling an Order

Any order in an active status (new, reviewing, ready, or printing) can be cancelled by clicking the red Cancel button. A browser prompt asks for a cancellation reason before the request is sent. The reason is stored in the cancel_reason field on the order and displayed on the order card in red. Providing a reason is strongly recommended — it helps staff understand why an order was stopped and gives context if the customer follows up. 
POST /api/orders/:id/transition
action=cancel&reason=Customer+requested+cancellation
Cancelled and failed orders remain fully visible in the dashboard and can be searched and filtered like any other order. They cannot be re-activated or transitioned to any further status.

​
Marking an Order as Failed

If a print job encounters a problem while the order is in Printing status, staff can click the red Failed button. A browser prompt asks for a failure reason before the request is sent. The reason is stored in the failure_reason field on the order and shown on the card in red. If PRINT_COMMAND is configured and the shell command exits with a non-zero code, the server marks the order failed automatically and uses the command’s stderr output as the failure reason — no manual action is required in that case. 
POST /api/orders/:id/transition
action=fail&reason=Paper+jam+on+printer+2
Only orders in printing status can be marked failed. Attempting to fail an order in any other status returns a 400 Bad Request error.

Build docs developers (and LLMs) love

Get started for freeTalk to us