PharmaFlow API

The PharmaFlow point of sale, inventory, and operations API. Paths are absolute: feature routes live under /api/v1, and /health stays on the root so a liveness probe never tracks the API version. The local default base URL is http://localhost:8000. Authentication is a Bearer JWT from POST /api/v1/auth/login unless an operation is marked public. Roles are admin and pharmacist in the seed data, and admin bypasses every role check.

Health

Service and database smoke checks.

• GET
  Check service and database health/health

Auth

Login, current user, and password change.

• POST
  Log in and issue an access token/api/v1/auth/login
• GET
  Read the signed in user/api/v1/auth/me
• POST
  Change the caller's password/api/v1/auth/change-password

Users

User records, roles, and password resets.

• GET
  List users/api/v1/users
• POST
  Create a user/api/v1/users
• GET
  Read a user/api/v1/users/{userId}
• PUT
  Update a user/api/v1/users/{userId}
• POST
  Reset a user's password/api/v1/users/{userId}/reset-password

Branches

Pharmacy branches and their lifecycle.

• GET
  List branches/api/v1/branches
• POST
  Create a branch/api/v1/branches
• GET
  Read a branch/api/v1/branches/{branchId}
• PUT
  Update a branch/api/v1/branches/{branchId}

Currency

Currency registry, branch currency, and exchange rates.

• GET
  List the currency registry/api/v1/currency
• POST
  Create a currency/api/v1/currency
• PATCH
  Update a currency/api/v1/currency/{code}
• GET
  Read the caller's branch currency/api/v1/currency/branch
• GET
  Read the currency overview/api/v1/currency/overview
• GET
  Resolve the effective rate/api/v1/currency/effective
• GET
  List exchange rates/api/v1/currency/rates
• POST
  File an exchange rate/api/v1/currency/rates
• POST
  Check a sale rate against tolerance/api/v1/currency/rates/check

Categories

Medicine categories used to group the catalogue.

• GET
  List the category catalogue/api/v1/categories
• POST
  Create a category/api/v1/categories
• PUT
  Update a category/api/v1/categories/{slug}
• DELETE
  Delete a category/api/v1/categories/{slug}

Medicines

The medicine catalogue, batch stock, and the controlled registry.

• GET
  List the medicine catalogue/api/v1/medicines
• POST
  Create a medicine/api/v1/medicines
• GET
  Read a medicine/api/v1/medicines/{medicineId}
• PUT
  Update a medicine/api/v1/medicines/{medicineId}
• DELETE
  Deactivate a medicine/api/v1/medicines/{medicineId}
• GET
  List a medicine's stock movements/api/v1/medicines/{medicineId}/movements
• GET
  List the controlled dispensing registry/api/v1/medicines/controlled/registry

Suppliers

Supplier records and contact details.

• GET
  List suppliers/api/v1/suppliers
• POST
  Create a supplier/api/v1/suppliers
• GET
  Read a supplier/api/v1/suppliers/{supplierId}
• PUT
  Update a supplier/api/v1/suppliers/{supplierId}
• DELETE
  Deactivate a supplier/api/v1/suppliers/{supplierId}

Sessions

Cash sessions, breaks, tender declarations, and Z-reports.

• POST
  Open a cash session/api/v1/sessions/open
• GET
  List closed cash sessions/api/v1/sessions/history
• GET
  Read the caller's open session/api/v1/sessions/current
• POST
  Start a break on the open session/api/v1/sessions/break/start
• POST
  End the caller's open break/api/v1/sessions/break/end
• POST
  Close the caller's cash session/api/v1/sessions/close
• POST
  Declare the counted cash/api/v1/sessions/tender
• GET
  List the caller's tender declarations/api/v1/sessions/tender/history
• GET
  List the sales in a session/api/v1/sessions/{sessionId}/sales
• GET
  Read a session Z-report/api/v1/sessions/{sessionId}/z-report

Sales

Sale creation, listing, and invoice allocation.

• GET
  List sales/api/v1/sales
• POST
  Create a sale/api/v1/sales
• GET
  Read a sale/api/v1/sales/{saleId}
• GET
  Read a sale invoice identity/api/v1/sales/{saleId}/invoice

Returns

Sale returns, restocking, and credit notes.

• GET
  Look up a returnable invoice/api/v1/returns/lookup/{invoiceNumber}
• GET
  List returns/api/v1/returns
• POST
  Create a return/api/v1/returns
• GET
  Read a return/api/v1/returns/{returnId}

Parked

Parked carts and their recall or void lifecycle.

• GET
  List parked carts/api/v1/parked
• POST
  Park a cart/api/v1/parked
• POST
  Recall a parked cart/api/v1/parked/{parkedId}/recall
• POST
  Void a parked cart/api/v1/parked/{parkedId}/void

Coupons

Coupon validation and administration.

• GET
  Validate a coupon code/api/v1/coupons/validate/{code}
• GET
  List coupons/api/v1/coupons
• POST
  Create a coupon/api/v1/coupons
• PUT
  Update a coupon/api/v1/coupons/{couponId}

Prescriptions

Prescriptions and their dispense or cancel flow.

• GET
  List prescriptions/api/v1/prescriptions
• POST
  Create a prescription/api/v1/prescriptions
• GET
  Get a prescription/api/v1/prescriptions/{prescriptionId}
• POST
  Dispense a prescription/api/v1/prescriptions/{prescriptionId}/dispense
• POST
  Cancel a prescription/api/v1/prescriptions/{prescriptionId}/cancel

Purchases

Batch receipts, expiring stock, and the movement ledger.

• GET
  List received batches/api/v1/purchases
• POST
  Receive a batch/api/v1/purchases
• GET
  List expiring batches/api/v1/purchases/expiring
• GET
  Read a received batch/api/v1/purchases/{batchId}
• PUT
  Write off a batch/api/v1/purchases/{batchId}/write-off
• GET
  List stock movements/api/v1/purchases/movements/all

Transfers

Stock transfers between branches.

• GET
  List stock transfers/api/v1/transfers
• POST
  Create a stock transfer/api/v1/transfers
• POST
  Create a batch stock transfer/api/v1/transfers/batch

Stockcount

Stock count sheets and variance submission.

• GET
  Read the branch stock count sheet/api/v1/stockcount
• POST
  Submit a stock count/api/v1/stockcount/submit

Customers

Customer records, credit limits, and the ledger.

• GET
  List customers/api/v1/customers
• POST
  Create a customer/api/v1/customers
• GET
  Get a customer ledger/api/v1/customers/{customerId}/ledger
• GET
  Get a customer/api/v1/customers/{customerId}
• PUT
  Update a customer/api/v1/customers/{customerId}
• POST
  Record a customer payment/api/v1/customers/{customerId}/payments

Dashboard

Summary metrics and branch comparison.

• GET
  Read the dashboard summary/api/v1/dashboard/summary
• GET
  Compare branch revenue/api/v1/dashboard/branch-comparison

Alerts

Low stock, expiring, and expired alerts.

• GET
  List low stock alerts/api/v1/alerts/low-stock
• GET
  List expiring batches/api/v1/alerts/expiry
• GET
  List expired batches/api/v1/alerts/expired

Audit

The append-only audit trail.

• GET
  List audit entries/api/v1/audit
• GET
  Read an audit entry/api/v1/audit/{auditId}

PurchaseOrders

Purchase orders from draft through received.

• GET
  List purchase orders/api/v1/purchase-orders
• POST
  Create a purchase order/api/v1/purchase-orders
• GET
  List suggested reorders/api/v1/purchase-orders/suggested
• GET
  Read a purchase order/api/v1/purchase-orders/{purchaseOrderId}
• PUT
  Send or cancel a purchase order/api/v1/purchase-orders/{purchaseOrderId}/status
• POST
  Receive a purchase order/api/v1/purchase-orders/{purchaseOrderId}/receive

Reports

Inventory, purchase, sales, pharmacist, and VAT reports.

• GET
  Report on the medicine inventory/api/v1/reports/inventory
• GET
  Report on purchase spend/api/v1/reports/purchases
• GET
  Report sales by pharmacist/api/v1/reports/sales/by-pharmacist
• GET
  Report on sales/api/v1/reports/sales
• GET
  Report on VAT by month/api/v1/reports/vat

Sync

Device registration, push, pull, and snapshots.

• POST
  Register a till/api/v1/sync/devices/register
• POST
  Push queued changes/api/v1/sync/push
• GET
  Pull changes since a revision/api/v1/sync/pull
• GET
  Snapshot the catalogue/api/v1/sync/snapshot
• GET
  List pending sync conflicts/api/v1/sync/conflicts
• POST
  Resolve a sync conflict/api/v1/sync/conflicts/{id}/resolve

Settings

Organisation settings, including the tax policy.

• GET
  Read the organisation settings/api/v1/settings
• PUT
  Update the organisation settings/api/v1/settings

Printing

Printers, receipt templates, and print jobs.

• GET
  List printers/api/v1/printing/printers
• POST
  Register a printer/api/v1/printing/printers
• PUT
  Update a printer/api/v1/printing/printers/{printerId}
• DELETE
  Remove a printer/api/v1/printing/printers/{printerId}
• GET
  List receipt templates/api/v1/printing/receipt-templates
• POST
  Create a receipt template/api/v1/printing/receipt-templates
• GET
  List print jobs/api/v1/printing/print-jobs
• POST
  Record a print job/api/v1/printing/print-jobs

Ops

Changelog entries and manager approvals.

• GET
  List the published changelog/api/v1/changelog
• POST
  Publish a changelog entry/api/v1/changelog
• GET
  List manager approvals/api/v1/approvals
• POST
  Request a manager approval/api/v1/approvals
• PUT
  Approve or reject an approval/api/v1/approvals/{approvalId}

Dispensing

Will-call pickup, generic search, and refill reminders.

• GET
  List the will-call queue/api/v1/dispensing/will-call
• POST
  Add a will-call pickup/api/v1/dispensing/will-call
• PUT
  Collect a will-call pickup/api/v1/dispensing/will-call/{willCallId}/pickup
• GET
  Search medicines by generic name/api/v1/dispensing/generic-search
• GET
  List pending refill reminders/api/v1/dispensing/refills
• POST
  Create a refill reminder/api/v1/dispensing/refills

SupplierFinance

Supplier invoices, payments, reorder suggestions, and quarantine.

• GET
  List supplier invoices/api/v1/supplier-finance/invoices
• POST
  Record a supplier invoice/api/v1/supplier-finance/invoices
• POST
  Record a payment on an invoice/api/v1/supplier-finance/invoices/{invoiceId}/payments
• GET
  List reorder suggestions/api/v1/supplier-finance/reorder-suggestions
• POST
  Quarantine or release a batch/api/v1/supplier-finance/batches/{batchId}/quarantine

Compliance

Statutory books, the EFRIS preview, and devices.

• GET
  List the prescription book/api/v1/compliance/prescription-book
• GET
  List the classified drugs book/api/v1/compliance/classified-drugs-book
• GET
  Preview the EFRIS payload for a sale/api/v1/compliance/efris-preview/{saleId}
• GET
  List registered devices/api/v1/compliance/devices
• POST
  Revoke a device/api/v1/compliance/devices/{deviceId}/revoke
• POST
  Restore a revoked device/api/v1/compliance/devices/{deviceId}/restore

Marketing

Public marketing contact and enquiry endpoints.

• POST
  Record a marketing enquiry/api/v1/marketing/contact

Images

Presigned uploads for medicine photos and branding.

• POST
  Create a medicine photo upload URL/api/v1/images/medicines/upload-url
• POST
  Attach an uploaded photo to a medicine/api/v1/images/medicines/{medicineId}/image
• POST
  Create a branding logo upload URL/api/v1/images/branding/upload-url
• PUT
  Set the organisation logo/api/v1/images/branding/logo