Developer

API Reference

All endpoints are under /api and accessed through the frontend proxy at http://<machine>:1994/api. The backend is never directly reachable.

Authentication

All routes except /auth/status, /auth/login, /auth/register, and the one-time POST /settings require the nodedr_session HttpOnly cookie. Admin-only routes additionally require the admin role on the authenticated account.

To authenticate: POST /api/auth/login with { "email": "...", "password": "..." }. The session cookie is set automatically on success and included in all subsequent requests by the browser.

Base URL

http://<machine>:1994/api

All requests go to the Next.js frontend, which server-side proxies /api/* to the internal backend. The backend is never directly accessible from the network.

Response format

All responses are JSON. Errors return a { "error": "message" } body with an appropriate HTTP status code (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Error, 500 Internal Server Error).

Endpoint table

Method	Path	Auth	Description
GET	/api/auth/status	None	Whether an admin account has been created yet (drives onboarding redirect)
POST	/api/auth/register	None	Create the first admin account (one-time, disabled once an admin exists)
POST	/api/auth/login	None	Authenticate with email + password; sets nodedr_session cookie
POST	/api/auth/logout	Session	Invalidate the current session cookie
POST	/api/auth/change-password	Session	Change the authenticated user's password
GET	/api/auth/users	Admin	List all staff accounts
POST	/api/auth/users	Admin	Create a new staff account
PUT	/api/auth/users/:id	Admin	Update a staff account (name, role, active state, password reset)
GET	/api/settings	Session	Read shop settings (currency, tax, loyalty, receipt config)
POST	/api/settings	None	Initial onboarding — create shop settings (one-time)
PUT	/api/settings	Admin	Update shop settings
GET	/api/products	Session	List all products; supports ?search=&category= query params
POST	/api/products	Admin	Create a new product
GET	/api/products/:id	Session	Get a single product by ID
PUT	/api/products/:id	Admin	Update a product
DELETE	/api/products/:id	Admin	Delete a product
GET	/api/products/barcode/:code	Session	Look up a product by barcode
GET	/api/products/low-stock	Session	Products at or below the low-stock threshold
GET	/api/customers	Session	List customers; supports ?search= and ?page= params
POST	/api/customers	Session	Create a customer
PUT	/api/customers/:id	Session	Update a customer
GET	/api/customers/phone/:phone	Session	Look up a customer by phone number
GET	/api/customers/top-loyalty	Session	Top customers ranked by current loyalty point balance
POST	/api/customers/:id/settle-due	Session	Record a payment against a customer's due balance
GET	/api/customers/:id/due-payments	Session	List all due payments for a customer
POST	/api/invoices	Session	Finalize a sale — server computes price, tax, discount, loyalty. Can include returns for exchange.
GET	/api/invoices	Session	Paginated sales history; supports ?search=&from=&to=&paymentMethod= params
GET	/api/invoices/summary	Session	Dashboard stat cards — today's revenue, count, average order value
GET	/api/invoices/analytics	Session	Chart data — revenue trend, top products, payment method mix
GET	/api/invoices/export.csv	Admin	Full sales history as CSV; supports ?from=&to= date range
GET	/api/invoices/:id	Session	Get a single invoice with all line items
POST	/api/returns	Session	Standalone return against a past invoice — restocks items, issues refund or store credit
GET	/api/returns/by-invoice/:invoiceId	Session	All returns made against an invoice (used to compute remaining returnable quantity)
GET	/api/print/:invoiceId/receipt	Session	Self-printing HTML receipt — opens a page and calls window.print()
GET	/api/print/:invoiceId/pdf	Session	Server-generated PDF receipt download
GET	/api/masters/summary	Admin	Row counts for all reference data tables
POST	/api/masters/tax-codes/import	Admin	Import HSN/SAC CSV — replaces existing rows
GET	/api/masters/tax-codes/search	Session	Autocomplete HSN/SAC codes; ?q=&type=HSN\|SAC
POST	/api/masters/pincodes/import	Admin	Import PIN code CSV — replaces existing rows
GET	/api/masters/pincodes/:code	Session	Look up a PIN code for city/state autofill
POST	/api/masters/ifsc/import	Admin	Import IFSC code CSV — replaces existing rows
GET	/api/masters/ifsc/:code	Session	Look up an IFSC code for bank/branch details

Example — finalize a sale

POST /api/invoices
Content-Type: application/json
Cookie: nodedr_session=<your-session-cookie>

{
  "customerId": 42,
  "items": [
    { "productId": 7, "quantity": 2 },
    { "productId": 15, "quantity": 1 }
  ],
  "paymentMethod": "UPI",
  "amountPaid": 250.00,
  "discountPercent": 5,
  "loyaltyRedeemed": 10.00
}

// The server computes final price, tax, discount, loyalty deduction
// from the catalog and settings — client values are never trusted for money.

Example — export sales CSV

GET /api/invoices/export.csv?from=2026-07-01&to=2026-07-25
Cookie: nodedr_session=<admin-session-cookie>

# Returns Content-Type: text/csv with filename attachment header

PreviousBackup & Restore NextSecurity Model