Skip to content

API Overview

Prism's HTTP surface is an Express monolith (mounted in index.js) plus a small set of serverless (Lambda) endpoints in the prism-services repo. It is overwhelmingly POST-based, JSON-bodied, and token-authenticated via custom headers. Many endpoints enqueue work rather than completing it synchronously.

Validation legend: ✅ verified against source · ❔ representative, verify

1. Base paths and their mounts

All mounts are in index.js (route-mounting block). Full per-route tables: Endpoint Reference.

Base path Router file Purpose Typical auth
/crm_api routes/crm.js Legacy — 100+ staff/web endpoints (customers, campaigns, ingestion) authMiddleware (many open)
/crm_api/v2 routes/crmv2.js New v2 endpoints (dashboard data, Gupshup partner) mixed / open
(root) routes/injestion.js Order ingestion + POS loyalty (/injestion/*, /api/*, /sync/*) crm_offer_middleware, injestion_middleware, or open
/integration/v1 routes/prismIntegration.js 3rd-party POS integration (users, loyalty, rewards, wallet) crm_offer_middleware (all)
/posist/v1 routes/posistLoyaltyIntegration.js Posist loyalty/coupon integration open ⚠
/stats routes/stats.js Dashboard metrics (12 endpoints) authMiddleware (all)
(via crm.js) routes/prism_routes/* Sub-features: campaign_tag, digital_bill, fraud_rules, loyalty_rewards, order_360, qr_code, whatsapp_login per-feature

The prism-services Lambdas expose their own HTTP endpoints (/crm_api/injestion/{pos}, /whatsapp/send, /whatsapp/receipts) — see Endpoint Reference §Serverless.

2. Request & response conventions

  • Method: almost everything is POST, even reads (e.g. POST /get/customer/details, POST /stats/metrics/orders). Body carries all inputs. Rare GETs exist (GET /track/whatsapp/link/:token).
  • Body: JSON (or url-encoded form). Common tenant/identity fields: userId, business_id / businessId, parent_business_id, parent_id, contactMappingId.
  • Auth headers (never Bearer unless noted):
  • token: <value> — staff/app auth (authMiddleware, adminMiddleware, injestion_middleware, thirdPartyMiddleware).
  • Authorization: <raw-token> — POS integration (crm_offer_middleware, MongoDB authorization_token).
  • Authorization: Bearer <jwt> — internal JWT routes (jwtMiddleware, jwtWhatsappMiddleware).
  • source: web|mobile — branches authMiddleware.
  • x-trace-id — optional; correlates logs (else auto-generated).
  • Auth details: Authentication.

3. Common response / error shapes

There is no single global envelope; two families dominate.

Integration family (crm_offer_middleware, /integration/v1, /injestion/api/*) — the status/error_code shape ✅: 

{ "status": 0, "error_code": "uE_101", "error_message": "Authentication Failed" }
- status: 1 = success, status: 0 = failure. Error codes are uE_<n> (e.g. uE_101 = auth failure, emitted by crm_offer_middleware).

Staff family (authMiddleware, adminMiddleware) — plain message on auth failure ✅: 

{ "message": "invalid credentials" }   // 403
{ "message": "authentication failed" } // 500 (fail-closed)

Ingestion / enqueue — a lightweight ack (representative ❔): 

{ "status": 1 }

Success payloads vary per controller. Where this doc shows a success body it is marked representative — verify unless quoted from source.

4. Sync vs. enqueue

The single most important API behaviour in Prism: many POSTs return 200 after enqueuing, then a cron does the real work. (Full lifecycle: Request Lifecycle §2.)

flowchart LR
    A[POST endpoint] --> B{Work type}
    B -->|read| C[Query Mongo/MySQL/Redis] --> D[JSON result]
    B -->|write needing async| E[Insert into queue<br/>e.g. crm_queue status:0] --> F[200 accepted]
    F -.later.-> G[Cron / Lambda consumer<br/>processes the queue]
  • Fire-and-forget: POST /injestion/uengage (injestionController.crmQueue) inserts into crm_queue with status:0 and returns — order processing happens in the ingestion cron.
  • Dual ingestion path ⚠: the same order sources are also ingested by the prism-services orders-consumer Lambda writing to the same crm_queue. See Order Ingestion and map-05.
  • Synchronous: loyalty checks/redemptions (/api/redeemLoyalty, /integration/v1/redeem_points) and all /stats/* metrics respond with computed data inline.

When something "didn't happen", first decide whether the endpoint was sync or enqueue, then check the relevant queue (crm_queue, points queue, WhatsApp/SMS/push queues) — see Request Lifecycle §5.

Area Module doc
Order ingestion (/injestion/*) Order Ingestion
Loyalty & rewards (/integration/v1, /api/*Loyalty, loyalty_rewards) Loyalty
Wallet (/get_wallet_ledger, /deduct_wallet_points) Wallet
Campaigns (/create/bulk/campaign, add_config) Campaigns
Dashboard metrics (/stats/*) Dashboard Analytics
Digital bills (prism_routes/digital_bill) Digital Bills
WhatsApp (login + serverless send/receipts) WhatsApp