API Reference

API Reference

All endpoints are under /api and reached through the frontend's server-side proxy at http://<machine>:1994/api — the backend itself is never published to the host. Except /auth/status, /auth/login, /auth/register, and the one-time onboarding POST /settings, every route requires the nodedr_session cookie; admin-only routes also require the admin role.

Method & path	Purpose
GET /auth/status	Whether an admin account exists yet
POST /auth/register	Onboarding — create the first admin (once)
POST /auth/login / /logout	Session management
POST /auth/change-password	Change your own password
GET/POST/PUT /auth/users	Staff account management (admin only)
GET/POST/PUT /settings	Company/currency/GST/loyalty/receipt config (PUT is admin only)
GET/POST/PUT/DELETE /products	Catalog CRUD, +/barcode/:code, /low-stock
GET/POST/PUT /customers	Customer directory, +/phone/:phone lookup, +/top-loyalty ranking
POST /customers/:id/settle-due, GET /customers/:id/due-payments	Record / list payments against a customer's due balance
POST /invoices	Finalize a sale — server computes price, tax, discount, loyalty, due; decrements stock; fully transactional. Can carry returns/creditApplied to net an exchange against the same bill
GET /invoices, /invoices/summary, /invoices/:id	Sales history & dashboard totals
POST /returns	Standalone return against a past invoice — restocks quantity, refunds cash/UPI/card or store credit
GET /returns/by-invoice/:invoiceId	Returns already made against an invoice, for computing remaining returnable quantity
GET /invoices/analytics	Dashboard chart data — revenue trend, top products, payment mix
GET /invoices/export.csv	Sales history as CSV (optional ?from=&to= range)
GET /print/:invoiceId/receipt	Self-printing HTML receipt (opens in a new tab, calls window.print())
GET /print/:invoiceId/pdf	Downloads the receipt as a PDF file
GET /print/diagnostics, POST /print/test	USB printer self-check and test slip
GET /masters/summary	Row counts for the Reference Data settings tab
POST /masters/tax-codes/import, GET /masters/tax-codes/search	Import (admin only) / autocomplete HSN or SAC codes
POST /masters/pincodes/import, GET /masters/pincodes/:code	Import (admin only) / look up a PIN code
POST /masters/ifsc/import, GET /masters/ifsc/:code	Import (admin only) / look up an IFSC code

Security posture

• Passwords: bcrypt (cost 12); login is timing-uniform and returns an identical error for unknown-user vs. wrong-password. Rate-limited (10 / 15 min) on top of a global limiter (300 req/min).
• Sessions: HttpOnly, SameSite=Lax JWT cookie (HS256, algorithm pinned). Every request re-checks the account still exists and is active. Set COOKIE_SECURE=true when serving over HTTPS.
• Authorization: all data routes require auth; settings and staff management require admin. The last active admin can't be demoted or disabled.
• Server-authoritative money: price, tax, discount caps, loyalty value, and change are always computed server-side — the client only sends product ids, quantities, and intent.
• Input validation: every write endpoint validates with Zod (allowlisted fields, no mass assignment); all DB access is parameterized via Prisma. CSV imports are admin-only, capped at 25MB, parsed in-memory.
• Reduced surface: the backend is never published to the host; only the frontend (:1994) is reachable. Neither container runs privileged: true or needs host device access for anything except the opt-in USB printer passthrough.
• Secrets: the JWT signing secret is auto-generated on first boot and stored (mode 600) in the data volume — never in the repo.

Designed for a trusted local network (a shop's LAN or a single machine). It's HTTP by default; if you expose it beyond the counter, terminate HTTPS in front of it and set COOKIE_SECURE=true — see Installation § Where to run it.

For the always-current source of truth, read the route files directly under backend/src/routes/.