README docs frontend-handout/00-INDEX.md

Invoice Service — Mobile Frontend Integration Handout

Audience: Android, iOS, web-pos, and KDS teams
Service: invoice-services (Node.js microservice)
API prefix: /v1
Last reviewed against: codebase under invoice-services/src (routes, controllers, daily-sales module)

This pack is the single integration reference for native apps. Use the shared invoice object shape across sync, history, KDS, and dine-orders.

Documents in this pack

# File What to read
0 00-INDEX.md This index + endpoint map
1 01-AUTH-AND-CONVENTIONS.md Base URL, JWT, enums, flags, errors, realtime
2 02-INVOICE-SYNC.md POST /v1/invoices/sync — create/update orders
3 03-INVOICE-READ-CANCEL.md History, get-by-UUID, cancel
4 04-KDS.md Kitchen display list + status update + Ably
5 05-DINE-ORDERS.md Floor-plan tables with active dine-in orders
6 06-PAYLOAD-REFERENCE.md Full attribute index (every invoice + line field, web-pos / iOS columns)
7 07-DAILY-SALES.md Daily sales report

Internal / engineering docs (same service, denser): docs/INVOICE_*.md, docs/KDS_API.md, docs/DINE_ORDERS_API.md, docs/DAILY_SALES_API.md.

Endpoint map (all mobile-relevant APIs)

Method Path Auth Purpose Handout
POST /v1/invoices/sync JWT Upsert orders; assign order_no / customer_invoice_id 02
GET /v1/invoices/history JWT Paginated order history (sync-shaped) 03
GET /v1/invoices/:uuid JWT Single invoice by UUID (raw DB row today) 03
PUT /v1/invoices/:uuid/cancel JWT Cancel order (+ optional inventory return) 03
GET /v1/kds-orders JWT Kitchen queue for current business day 04
PUT /v1/kds-orders/:uuid JWT Mark done / rebump / line prepared 04
GET /v1/dine-orders JWT Tables + open/done dine-in invoices 05
GET /v1/daily-sales JWT Daily sales report (same as legacy today-sales-v3) 07
GET /v1/health no Health 01
GET /health no Liveness 01

Admin (/admin), queue admin (/v1/queue), and docs site are not for mobile POS clients.

Shared mental model (read this once)

  1. One invoice JSON shape is used for:
    • What you send on POST /sync (plus required request_id)
    • What you receive on history / KDS / dine-orders dinerOrderDetail
  2. Booleans are 0 / 1 numbers, not JSON true/false (except wrapper fields like status: true on some envelopes).
  3. Timestamps are Unix seconds (number), not ISO strings — except Ably payload updated_at / done_at which are ISO.
  4. POST /sync is async for DB persistence: HTTP 200 means numbers were assigned and a job was queued; DB may catch up slightly later. Prefer history/KDS/get after sync if you need committed rows.
  5. Tenant scope always comes from the JWT (customer_id, location_id). Do not rely on query params to switch tenant.
  6. Master-user product model only: customize with modifiers + addons. Do not build new flows around extras/materials.

Recommended client integration order

  1. Wire JWT + error envelope (01)
  2. Implement POST /sync with request_id idempotency (02)
  3. Implement cancel + history (03)
  4. If kitchen app: KDS + Ably (04)
  5. If floor plan / dine-in: dine-orders (05)
  6. If end-of-day / sales report: daily-sales (07)
  7. Keep 06 open while modeling DTOs

Legacy TRACK path → new path

Legacy (web-application / gateway) Invoice service
Sync via invoiceSyncV3 / TRACK invoice sync POST /v1/invoices/sync
PUT /api/v2/invoice-cancel/:uuid PUT /v1/invoices/:uuid/cancel
Orders history (TRACK) GET /v1/invoices/history
GET /kds-orders GET /v1/kds-orders
PUT /api/v2/kds-orders/:uuid / PUT /kds-order-status PUT /v1/kds-orders/:uuid
GET /dine-orders GET /v1/dine-orders
GET /today-sales-v3 GET /v1/daily-sales

Source of truth in code

Concern Path
Routes mount src/routes/v1/index.js → /v1
Invoice routes src/routes/v1/invoice.route.js
Sync / cancel validation src/validations/invoice.validation.js
Sync response mapper (reads) src/utils/invoice-sync-response-mapper.js
KDS validation contract src/validations/kds.validation.js
Dine-orders validation src/validations/dineOrders.validation.js
Daily sales route src/routes/v1/dailySales.route.js
Daily sales report src/daily-sales/createTodaySalesReport.js
Daily sales repository src/data/repositories/DailySalesRepository.js