Skip to content

API.md

Latest commit

 

History

History
352 lines (265 loc) · 5.57 KB

API.md

File metadata and controls

352 lines (265 loc) · 5.57 KB

PharmaScan API Documentation

Base URL: http://localhost:5000

All JSON APIs are under /api.

Authentication

PharmScan uses JWT bearer tokens.

  1. Login via POST /api/login
  2. Use the returned token in protected requests:
Authorization: Bearer <token>

Token lifetime is 8 hours.

Endpoints

POST /api/login

Authenticates a user and returns JWT + role payload.

Auth required: No

Request body:

{
  "username": "pharmacist",
  "password": "password123"
}

Success response 200:

{
  "message": "Login successful",
  "token": "<jwt>",
  "user": {
    "id": 1,
    "name": "Rph. Kumari",
    "username": "pharmacist",
    "role": "pharmacist"
  }
}

Error responses:

  • 400 missing username/password
  • 401 invalid credentials
  • 500 internal error

GET /api/drugs

Returns drug master list used by search/barcode workflows.

Auth required: No

Success response 200:

{
  "success": true,
  "drugs": [
    {
      "id": 1,
      "barcode": "100001",
      "dosage_form": "TAB",
      "generic_name": "METFORMIN",
      "brand_name": "GLUCOPHAGE",
      "dosage": "500MG"
    }
  ]
}

Error responses:

  • 500 database read failure

POST /api/dispense-logs

Persists a dispense/handover result for manager analytics.

Auth required: Yes

Request body:

{
  "patient_token": "T-1048",
  "drug_scanned": [],
  "drug_prescribed": [],
  "match_status": {}
}

Notes:

  • drug_scanned, drug_prescribed, and match_status are stored as JSON in MySQL.
  • patient_token is required.
  • For partial completion from scan flow, match_status may include:
    • isPartialCompletion: true
    • overrideReason: "Patient asked" | "Out of stock" | "Other"
  • In partial completion, unscanned prescribed items are represented in resultsSummary as type: "not_dispensed".
  • Counselling confirmation metadata is persisted in match_status:
    • counsellingAcknowledged: true
    • counsellingAcknowledgedAt: <ISO timestamp>

Success response 201:

{
  "success": true,
  "log_id": 123,
  "message": "Dispense logged successfully"
}

Error responses:

  • 400 missing patient token
  • 401 no token
  • 403 invalid/expired token
  • 500 write failure

POST /api/counselling/recommendations

Generates counselling advice per drug using LLM, cache, or fallback.

Auth required: Yes

Request body:

{
  "patientAge": 58,
  "patientSex": "female",
  "drugs": [
    {
      "genericName": "Metformin",
      "strength": "500mg",
      "brandName": "Glucophage"
    }
  ]
}

Success response 200:

{
  "success": true,
  "source": "llm",
  "recommendations": [
    {
      "key": "metformin__500mg__glucophage",
      "genericName": "Metformin",
      "strength": "500mg",
      "brandName": "Glucophage",
      "foodTiming": "with food",
      "pregnancyWarning": "...",
      "keyWarnings": ["...", "..."]
    }
  ]
}

source values:

  • llm fresh model output
  • llm-cache cache hit
  • fallback deterministic safety fallback

Error responses:

  • 400 missing required fields
  • 401 no token
  • 403 invalid/expired token

Note: timeouts and model failures intentionally return fallback 200 responses instead of hard errors.

GET /api/manager/stats?range=today|week|month

Returns KPI totals for dashboard cards.

Auth required: Yes

Success response 200:

{
  "success": true,
  "stats": {
    "totalDispensed": 42,
    "mismatches": 3,
    "overrides": 1
  }
}

GET /api/manager/dispensing-logs?limit=50

Returns recent dispensing log summaries for table views.

Auth required: Yes

Success response 200:

{
  "success": true,
  "logs": [
    {
      "id": 10,
      "patientToken": "T-1048",
      "timestamp": "2026-04-01T05:20:00.000Z",
      "pharmacistName": "Rph. Kumari",
      "status": "success",
      "drugCount": 3,
      "hasBrandDifferences": false,
      "hasMismatches": false,
      "hasQuantityMismatches": false,
      "quantityMismatchCount": 0,
      "overridden": false
    }
  ]
}

status values:

  • success
  • brand_diff
  • quantity_mismatch
  • mismatch

GET /api/manager/pharmacist-performance

Returns per-pharmacist totals and daily accuracy.

Auth required: Yes

Success response 200:

{
  "success": true,
  "pharmacists": [
    {
      "name": "Rph. Kumari",
      "dispensed": 12,
      "mismatches": 1,
      "accuracy": "91.7"
    }
  ]
}

GET /api/manager/analytics-summary?range=today|week|month

Returns aggregated analytics used by charts and watchlists.

Auth required: Yes

Success response 200 includes:

  • kpis
  • trends
  • watchlists
  • pharmacistAnalytics
  • categoryDistribution

GET /api/manager/ai-brief?range=today|week|month

Returns manager action brief, generated by LLM or fallback logic.

Auth required: Yes

Success response 200:

{
  "success": true,
  "brief": {
    "source": "llm",
    "summary": "...",
    "anomalies": ["..."],
    "actions": ["..."]
  }
}

brief.source values:

  • llm
  • fallback

GET /api/health

Health check for API and DB connectivity.

Auth required: No

Success response 200:

{
  "status": "ok",
  "database": "connected",
  "message": "PharmaScan API and MySQL Database are running smoothly",
  "timestamp": "2026-04-01T06:00:00.000Z"
}

Error response 500:

{
  "status": "error",
  "database": "disconnected",
  "error": "..."
}

Error Model

Common auth errors on protected endpoints:

  • 401: missing token
  • 403: invalid or expired token

Server error shape:

{
  "error": "Human-readable message"
}