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.

The orders API covers the full lifecycle entry point for print jobs. Customers use POST /api/orders to submit documents from the upload page; staff use GET /api/orders and GET /api/orders/:id from the admin dashboard to inspect and manage incoming work.

​
POST /api/orders

POST /api/orders
Content-Type: multipart/form-data
Submits a new print order. No authentication is required — this is the public customer endpoint. The request body must be multipart/form-data containing at least one file in the documents field. Per-document print settings are supplied as indexed fields (color_mode_0, print_style_0, etc.) matching the order in which files appear. The server automatically estimates costs for PDF documents by counting pages and looking up the matching rule in the pricing table. Non-PDF files and PDFs with no matching pricing rule receive a null cost — staff estimate those after review.

​
Request Fields

​
customer_name
string
Full name of the customer placing the order. Defaults to "Walk-in customer" if omitted.
​
phone
string
Customer phone number. Optional. Stored as-is; no validation is applied.
​
notes
string
Order-level notes visible to staff, e.g. "Need urgently". Optional.
​
documents
file
required
One or more files to print. Use the same field name documents for each file — multipart allows repeated field names. At least one file is required; submitting zero files returns a 400 error. Each file’s size must not exceed max_upload_mb (default 50 MB). The total request body must not exceed six times max_upload_mb.
​
color_mode_<n>
string
Color mode for the document at zero-based index n. Valid values: bw (black & white) or color. Defaults to bw if omitted.
​
print_style_<n>
string
Print style for document n. Valid values: single (single-sided) or double (double-sided). Defaults to single if omitted.
​
paper_size_<n>
string
Paper size for document n, e.g. A4, A3, Letter. Defaults to A4 if omitted.
​
copies_<n>
integer
Number of copies of document n. Must be between 1 and 99. Defaults to 1.
​
document_notes_<n>
string
Per-document notes for document n, e.g. "Print on glossy paper". Optional.

​
Response — 201 Created

{
  "ok": true,
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_name": "Jane Smith",
    "phone": "9876543210",
    "notes": "Need urgently",
    "status": "new",
    "total_estimated_cost": 14.0,
    "estimated_total": 14.0,
    "cancel_reason": null,
    "failure_reason": null,
    "document_count": 1,
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:00",
    "documents": [
      {
        "id": "doc-uuid",
        "original_name": "report.pdf",
        "page_count": 7,
        "color_mode": "bw",
        "print_style": "single",
        "paper_size": "A4",
        "copies": 1,
        "estimated_cost": 14.0
      }
    ]
  }
}
total_estimated_cost and estimated_cost are null when the document is not a PDF or when no matching pricing rule exists — in that case the cost is estimated after staff review. estimated_total is always present and mirrors total_estimated_cost.

​
Error Cases

StatusCondition
400 Bad RequestNo files attached ({"error": "At least one file required"})
400 Bad RequestA file exceeds max_upload_mb ({"error": "<filename> exceeds N MB"})
400 Bad RequestA file has zero bytes ({"error": "<filename> is empty"})
400 Bad Requestcopies_<n> is not a valid number
400 Bad RequestContent-Type is not multipart/form-data
413 Request Entity Too LargeTotal body exceeds 6× max_upload_mb

​
Example

curl -X POST http://localhost:8000/api/orders \
  -F "customer_name=Jane Smith" \
  -F "phone=9876543210" \
  -F "notes=Need urgently" \
  -F "documents=@report.pdf" \
  -F "color_mode_0=bw" \
  -F "print_style_0=single" \
  -F "paper_size_0=A4" \
  -F "copies_0=1"
To submit multiple documents in one order, repeat the documents field and add a matching set of indexed settings for each: 
curl -X POST http://localhost:8000/api/orders \
  -F "customer_name=Jane Smith" \
  -F "documents=@report.pdf" \
  -F "color_mode_0=bw" \
  -F "print_style_0=single" \
  -F "paper_size_0=A4" \
  -F "copies_0=2" \
  -F "documents=@poster.png" \
  -F "color_mode_1=color" \
  -F "print_style_1=single" \
  -F "paper_size_1=A3" \
  -F "copies_1=1"

​
GET /api/orders

GET /api/orders
Returns all orders as a JSON array, sorted by created_at descending (newest first). Requires admin authentication via X-Admin-Token header or ?token= query parameter.

​
Query Parameters

​
search
string
Free-text search across order UUID, customer name, and phone number. Case-insensitive substring match. Returns all orders if omitted.
​
status
string
Filter by order status. Valid values: new, reviewing, ready, printing, printed, cancelled, failed. Returns all statuses if omitted.

​
Response — 200 OK

A JSON array where each element has the same shape as the order object in the POST /api/orders response. Every order object always includes document_count, estimated_total, cancel_reason, and failure_reason — these are not additional fields unique to this endpoint, they are part of every order response. 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_name": "Jane Smith",
    "phone": "9876543210",
    "notes": "Need urgently",
    "status": "new",
    "total_estimated_cost": 14.0,
    "estimated_total": 14.0,
    "cancel_reason": null,
    "failure_reason": null,
    "document_count": 1,
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:00",
    "documents": [...]
  }
]

​
Example

# List all orders
curl http://localhost:8000/api/orders \
  -H "X-Admin-Token: your-secret-token"

# Filter to new orders matching "Jane"
curl "http://localhost:8000/api/orders?status=new&search=Jane" \
  -H "X-Admin-Token: your-secret-token"

​
GET /api/orders/:id

GET /api/orders/:id
Returns a single order object by its UUID. Requires admin authentication.

​
Path Parameter

​
id
string
required
The UUID of the order, e.g. 550e8400-e29b-41d4-a716-446655440000.

​
Response — 200 OK

A single order object with the same shape described in GET /api/orders.

​
Error Cases

StatusBody
404 Not Found{"error": "Not found"}
401 Unauthorized{"error": "Admin token required"}

​
Example

curl http://localhost:8000/api/orders/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Admin-Token: your-secret-token"

Build docs developers (and LLMs) love

Get started for freeTalk to us