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.

Once a customer submits an order it enters the new status and staff advance it through a defined lifecycle using the transition and print endpoints. Both endpoints require admin authentication. The transition endpoint accepts an application/x-www-form-urlencoded body; the print endpoint takes no request body — only the order UUID in the path is required.

​
POST /api/orders/:id/transition

POST /api/orders/:id/transition
Content-Type: application/x-www-form-urlencoded
Advances or terminates an order’s status by applying a named action. The server validates that the order’s current status matches the action’s required precondition and returns the updated order on success.

​
Path Parameter

​
id
string
required
The UUID of the order to transition.

​
Request Fields

​
action
string
required
The transition to apply. Must be one of: start_review, approve, start_print, complete, fail, cancel.
​
reason
string
A human-readable explanation. Required when action is fail or cancel. Stored in failure_reason or cancel_reason respectively and displayed in the admin dashboard.

​
Status Flow

ActionRequired Current StatusNext Status
start_reviewnewreviewing
approvereviewingready
start_printreadyprinting
completeprintingprinted
failprintingfailed
cancelany active statuscancelled
Active statuses that can be cancelled are: new, reviewing, ready, and printing. Attempting to cancel an already-terminal order (printed, cancelled, failed) returns a 400 error.
The start_print action is used internally by POST /api/orders/:id/print. You can call it manually via the transition endpoint if you want to mark an order as printing without executing the PRINT_COMMAND (for example, if printing was done outside the system).

​
Response — 200 OK

{
  "ok": true,
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_name": "Jane Smith",
    "status": "ready",
    "updated_at": "2024-01-15T10:35:00",
    "...": "...full order object..."
  }
}

​
Error Cases

StatusCondition
400 Bad Requestaction is not a recognised value ({"error": "Invalid action"})
400 Bad RequestOrder is not in the required status for the given action
400 Bad RequestAttempting to cancel a non-active order
404 Not FoundNo order exists with the given id
401 UnauthorizedMissing or invalid admin token

​
Examples

# Move an order from "new" to "reviewing"
curl -X POST http://localhost:8000/api/orders/<id>/transition \
  -H "X-Admin-Token: your-token" \
  -d "action=start_review"

# Approve a reviewed order (reviewing → ready)
curl -X POST http://localhost:8000/api/orders/<id>/transition \
  -H "X-Admin-Token: your-token" \
  -d "action=approve"

# Mark a printing order as printed
curl -X POST http://localhost:8000/api/orders/<id>/transition \
  -H "X-Admin-Token: your-token" \
  -d "action=complete"

# Cancel with a reason
curl -X POST http://localhost:8000/api/orders/<id>/transition \
  -H "X-Admin-Token: your-token" \
  -d "action=cancel&reason=Customer+cancelled"

# Mark as failed with a reason
curl -X POST http://localhost:8000/api/orders/<id>/transition \
  -H "X-Admin-Token: your-token" \
  -d "action=fail&reason=Paper+jam+during+print"

​
POST /api/orders/:id/print

POST /api/orders/:id/print
Combines a status transition (ready → printing) with a shell print command. The order must currently be in the ready status. The endpoint iterates over every document in the order and runs the configured PRINT_COMMAND once per document, substituting document-specific placeholders. Requires admin authentication.

​
Path Parameter

​
id
string
required
The UUID of the order to print.

​
How PRINT_COMMAND Works

The PRINT_COMMAND string from .env is a shell template with the following placeholders, all replaced per document at runtime:
PlaceholderValue
{file}Absolute path to the stored document file
{copies}Number of copies requested
{paper}Paper size, e.g. A4
{color}Color mode, bw or color
{style}Print style, single or double
Example .env configuration using CUPS: 
PRINT_COMMAND=lp -n {copies} -o media={paper} -o sides={style}-sided "{file}"
If PRINT_COMMAND is empty, the endpoint still transitions the order to printing but does not run any shell command. This is useful for shops that manage physical printing manually but want to track order state in the system.

​
Response — 200 OK

{
  "ok": true,
  "printed": true,
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "printing",
    "...": "...full order object..."
  }
}
printed is false when PRINT_COMMAND was not configured — the status is still advanced to printing.

​
Error Cases

StatusCondition
400 Bad RequestOrder status is not ready ({"error": "Order must be ready first"})
404 Not FoundNo order with the given id
401 UnauthorizedMissing or invalid admin token
500 Internal Server ErrorPRINT_COMMAND exited non-zero; order is automatically transitioned to failed with failure_reason set to stderr output
When the print command fails the order is transitioned to failed automatically. The 500 response body includes both "error" (the stderr output) and "order" (the updated failed order object). Staff should check failure_reason on the order to diagnose the problem.

​
Example

# Trigger printing for a ready order
curl -X POST http://localhost:8000/api/orders/<id>/print \
  -H "X-Admin-Token: your-token"

Build docs developers (and LLMs) love

Get started for freeTalk to us