---
seo:
  description: >-
    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…
sidebar:
  label: Overview
title: 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.

Version 0.1.0

Base URL: `http://localhost:8000`

## Health

Service and database smoke checks.

- [`GET /health`](/api/health/get-health) — Check service and database health.

## Auth

Login, current user, and password change.

- [`POST /api/v1/auth/login`](/api/auth/login-user) — Log in and issue an access token.
- [`GET /api/v1/auth/me`](/api/auth/get-current-user) — Read the signed in user.
- [`POST /api/v1/auth/change-password`](/api/auth/change-password) — Change the caller's password.

## Users

User records, roles, and password resets.

- [`GET /api/v1/users`](/api/users/list-users) — List users.
- [`POST /api/v1/users`](/api/users/create-user) — Create a user.
- [`GET /api/v1/users/{userId}`](/api/users/get-user) — Read a user.
- [`PUT /api/v1/users/{userId}`](/api/users/update-user) — Update a user.
- [`POST /api/v1/users/{userId}/reset-password`](/api/users/reset-user-password) — Reset a user's password.

## Branches

Pharmacy branches and their lifecycle.

- [`GET /api/v1/branches`](/api/branches/list-branches) — List branches.
- [`POST /api/v1/branches`](/api/branches/create-branch) — Create a branch.
- [`GET /api/v1/branches/{branchId}`](/api/branches/get-branch) — Read a branch.
- [`PUT /api/v1/branches/{branchId}`](/api/branches/update-branch) — Update a branch.

## Currency

Currency registry, branch currency, and exchange rates.

- [`GET /api/v1/currency`](/api/currency/list-currencies) — List the currency registry.
- [`POST /api/v1/currency`](/api/currency/create-currency) — Create a currency.
- [`PATCH /api/v1/currency/{code}`](/api/currency/update-currency) — Update a currency.
- [`GET /api/v1/currency/branch`](/api/currency/get-branch-currency) — Read the caller's branch currency.
- [`GET /api/v1/currency/overview`](/api/currency/get-currency-overview) — Read the currency overview.
- [`GET /api/v1/currency/effective`](/api/currency/get-effective-rate) — Resolve the effective rate.
- [`GET /api/v1/currency/rates`](/api/currency/list-exchange-rates) — List exchange rates.
- [`POST /api/v1/currency/rates`](/api/currency/create-exchange-rate) — File an exchange rate.
- [`POST /api/v1/currency/rates/check`](/api/currency/check-exchange-rate-tolerance) — Check a sale rate against tolerance.

## Categories

Medicine categories used to group the catalogue.

- [`GET /api/v1/categories`](/api/categories/list-categories) — List the category catalogue.
- [`POST /api/v1/categories`](/api/categories/create-category) — Create a category.
- [`PUT /api/v1/categories/{slug}`](/api/categories/update-category) — Update a category.
- [`DELETE /api/v1/categories/{slug}`](/api/categories/delete-category) — Delete a category.

## Medicines

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

- [`GET /api/v1/medicines`](/api/medicines/list-medicines) — List the medicine catalogue.
- [`POST /api/v1/medicines`](/api/medicines/create-medicine) — Create a medicine.
- [`GET /api/v1/medicines/{medicineId}`](/api/medicines/get-medicine) — Read a medicine.
- [`PUT /api/v1/medicines/{medicineId}`](/api/medicines/update-medicine) — Update a medicine.
- [`DELETE /api/v1/medicines/{medicineId}`](/api/medicines/delete-medicine) — Deactivate a medicine.
- [`GET /api/v1/medicines/{medicineId}/movements`](/api/medicines/get-medicine-movements) — List a medicine's stock movements.
- [`GET /api/v1/medicines/controlled/registry`](/api/medicines/get-controlled-registry) — List the controlled dispensing registry.

## Suppliers

Supplier records and contact details.

- [`GET /api/v1/suppliers`](/api/suppliers/list-suppliers) — List suppliers.
- [`POST /api/v1/suppliers`](/api/suppliers/create-supplier) — Create a supplier.
- [`GET /api/v1/suppliers/{supplierId}`](/api/suppliers/get-supplier) — Read a supplier.
- [`PUT /api/v1/suppliers/{supplierId}`](/api/suppliers/update-supplier) — Update a supplier.
- [`DELETE /api/v1/suppliers/{supplierId}`](/api/suppliers/delete-supplier) — Deactivate a supplier.

## Sessions

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

- [`POST /api/v1/sessions/open`](/api/sessions/open-session) — Open a cash session.
- [`GET /api/v1/sessions/history`](/api/sessions/list-session-history) — List closed cash sessions.
- [`GET /api/v1/sessions/current`](/api/sessions/get-current-session) — Read the caller's open session.
- [`POST /api/v1/sessions/break/start`](/api/sessions/start-break) — Start a break on the open session.
- [`POST /api/v1/sessions/break/end`](/api/sessions/end-break) — End the caller's open break.
- [`POST /api/v1/sessions/close`](/api/sessions/close-session) — Close the caller's cash session.
- [`POST /api/v1/sessions/tender`](/api/sessions/declare-tender) — Declare the counted cash.
- [`GET /api/v1/sessions/tender/history`](/api/sessions/list-tender-history) — List the caller's tender declarations.
- [`GET /api/v1/sessions/{sessionId}/sales`](/api/sessions/get-session-sales) — List the sales in a session.
- [`GET /api/v1/sessions/{sessionId}/z-report`](/api/sessions/get-z-report) — Read a session Z-report.

## Sales

Sale creation, listing, and invoice allocation.

- [`GET /api/v1/sales`](/api/sales/list-sales) — List sales.
- [`POST /api/v1/sales`](/api/sales/create-sale) — Create a sale.
- [`GET /api/v1/sales/{saleId}`](/api/sales/get-sale) — Read a sale.
- [`GET /api/v1/sales/{saleId}/invoice`](/api/sales/get-sale-invoice) — Read a sale invoice identity.

## Returns

Sale returns, restocking, and credit notes.

- [`GET /api/v1/returns/lookup/{invoiceNumber}`](/api/returns/get-return-lookup) — Look up a returnable invoice.
- [`GET /api/v1/returns`](/api/returns/list-returns) — List returns.
- [`POST /api/v1/returns`](/api/returns/create-return) — Create a return.
- [`GET /api/v1/returns/{returnId}`](/api/returns/get-return) — Read a return.

## Parked

Parked carts and their recall or void lifecycle.

- [`GET /api/v1/parked`](/api/parked/list-parked) — List parked carts.
- [`POST /api/v1/parked`](/api/parked/park-cart) — Park a cart.
- [`POST /api/v1/parked/{parkedId}/recall`](/api/parked/recall-parked) — Recall a parked cart.
- [`POST /api/v1/parked/{parkedId}/void`](/api/parked/void-parked) — Void a parked cart.

## Coupons

Coupon validation and administration.

- [`GET /api/v1/coupons/validate/{code}`](/api/coupons/validate-coupon) — Validate a coupon code.
- [`GET /api/v1/coupons`](/api/coupons/list-coupons) — List coupons.
- [`POST /api/v1/coupons`](/api/coupons/create-coupon) — Create a coupon.
- [`PUT /api/v1/coupons/{couponId}`](/api/coupons/update-coupon) — Update a coupon.

## Prescriptions

Prescriptions and their dispense or cancel flow.

- [`GET /api/v1/prescriptions`](/api/prescriptions/list-prescriptions) — List prescriptions.
- [`POST /api/v1/prescriptions`](/api/prescriptions/create-prescription) — Create a prescription.
- [`GET /api/v1/prescriptions/{prescriptionId}`](/api/prescriptions/get-prescription) — Get a prescription.
- [`POST /api/v1/prescriptions/{prescriptionId}/dispense`](/api/prescriptions/dispense-prescription) — Dispense a prescription.
- [`POST /api/v1/prescriptions/{prescriptionId}/cancel`](/api/prescriptions/cancel-prescription) — Cancel a prescription.

## Purchases

Batch receipts, expiring stock, and the movement ledger.

- [`GET /api/v1/purchases`](/api/purchases/list-purchases) — List received batches.
- [`POST /api/v1/purchases`](/api/purchases/create-purchase) — Receive a batch.
- [`GET /api/v1/purchases/expiring`](/api/purchases/list-expiring-purchases) — List expiring batches.
- [`GET /api/v1/purchases/{batchId}`](/api/purchases/get-purchase) — Read a received batch.
- [`PUT /api/v1/purchases/{batchId}/write-off`](/api/purchases/write-off-purchase) — Write off a batch.
- [`GET /api/v1/purchases/movements/all`](/api/purchases/list-purchase-movements) — List stock movements.

## Transfers

Stock transfers between branches.

- [`GET /api/v1/transfers`](/api/transfers/list-transfers) — List stock transfers.
- [`POST /api/v1/transfers`](/api/transfers/create-transfer) — Create a stock transfer.
- [`POST /api/v1/transfers/batch`](/api/transfers/create-batch-transfer) — Create a batch stock transfer.

## Stockcount

Stock count sheets and variance submission.

- [`GET /api/v1/stockcount`](/api/stockcount/get-stock-count-sheet) — Read the branch stock count sheet.
- [`POST /api/v1/stockcount/submit`](/api/stockcount/submit-stock-count) — Submit a stock count.

## Customers

Customer records, credit limits, and the ledger.

- [`GET /api/v1/customers`](/api/customers/list-customers) — List customers.
- [`POST /api/v1/customers`](/api/customers/create-customer) — Create a customer.
- [`GET /api/v1/customers/{customerId}/ledger`](/api/customers/get-customer-ledger) — Get a customer ledger.
- [`GET /api/v1/customers/{customerId}`](/api/customers/get-customer) — Get a customer.
- [`PUT /api/v1/customers/{customerId}`](/api/customers/update-customer) — Update a customer.
- [`POST /api/v1/customers/{customerId}/payments`](/api/customers/create-customer-payment) — Record a customer payment.

## Dashboard

Summary metrics and branch comparison.

- [`GET /api/v1/dashboard/summary`](/api/dashboard/get-dashboard-summary) — Read the dashboard summary.
- [`GET /api/v1/dashboard/branch-comparison`](/api/dashboard/get-branch-comparison) — Compare branch revenue.

## Alerts

Low stock, expiring, and expired alerts.

- [`GET /api/v1/alerts/low-stock`](/api/alerts/list-low-stock-alerts) — List low stock alerts.
- [`GET /api/v1/alerts/expiry`](/api/alerts/list-expiry-alerts) — List expiring batches.
- [`GET /api/v1/alerts/expired`](/api/alerts/list-expired-alerts) — List expired batches.

## Audit

The append-only audit trail.

- [`GET /api/v1/audit`](/api/audit/list-audit-entries) — List audit entries.
- [`GET /api/v1/audit/{auditId}`](/api/audit/get-audit-entry) — Read an audit entry.

## PurchaseOrders

Purchase orders from draft through received.

- [`GET /api/v1/purchase-orders`](/api/purchaseorders/list-purchase-orders) — List purchase orders.
- [`POST /api/v1/purchase-orders`](/api/purchaseorders/create-purchase-order) — Create a purchase order.
- [`GET /api/v1/purchase-orders/suggested`](/api/purchaseorders/list-suggested-purchase-orders) — List suggested reorders.
- [`GET /api/v1/purchase-orders/{purchaseOrderId}`](/api/purchaseorders/get-purchase-order) — Read a purchase order.
- [`PUT /api/v1/purchase-orders/{purchaseOrderId}/status`](/api/purchaseorders/update-purchase-order-status) — Send or cancel a purchase order.
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/receive`](/api/purchaseorders/receive-purchase-order) — Receive a purchase order.

## Reports

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

- [`GET /api/v1/reports/inventory`](/api/reports/get-inventory-report) — Report on the medicine inventory.
- [`GET /api/v1/reports/purchases`](/api/reports/get-purchases-report) — Report on purchase spend.
- [`GET /api/v1/reports/sales/by-pharmacist`](/api/reports/get-pharmacist-sales-report) — Report sales by pharmacist.
- [`GET /api/v1/reports/sales`](/api/reports/get-sales-report) — Report on sales.
- [`GET /api/v1/reports/vat`](/api/reports/get-vat-report) — Report on VAT by month.

## Sync

Device registration, push, pull, and snapshots.

- [`POST /api/v1/sync/devices/register`](/api/sync/register-sync-device) — Register a till.
- [`POST /api/v1/sync/push`](/api/sync/push-sync-changes) — Push queued changes.
- [`GET /api/v1/sync/pull`](/api/sync/pull-sync-changes) — Pull changes since a revision.
- [`GET /api/v1/sync/snapshot`](/api/sync/get-sync-snapshot) — Snapshot the catalogue.
- [`GET /api/v1/sync/conflicts`](/api/sync/list-sync-conflicts) — List pending sync conflicts.
- [`POST /api/v1/sync/conflicts/{id}/resolve`](/api/sync/resolve-sync-conflict) — Resolve a sync conflict.

## Settings

Organisation settings, including the tax policy.

- [`GET /api/v1/settings`](/api/settings/get-settings) — Read the organisation settings.
- [`PUT /api/v1/settings`](/api/settings/update-settings) — Update the organisation settings.

## Printing

Printers, receipt templates, and print jobs.

- [`GET /api/v1/printing/printers`](/api/printing/list-printers) — List printers.
- [`POST /api/v1/printing/printers`](/api/printing/create-printer) — Register a printer.
- [`PUT /api/v1/printing/printers/{printerId}`](/api/printing/update-printer) — Update a printer.
- [`DELETE /api/v1/printing/printers/{printerId}`](/api/printing/delete-printer) — Remove a printer.
- [`GET /api/v1/printing/receipt-templates`](/api/printing/list-receipt-templates) — List receipt templates.
- [`POST /api/v1/printing/receipt-templates`](/api/printing/create-receipt-template) — Create a receipt template.
- [`GET /api/v1/printing/print-jobs`](/api/printing/list-print-jobs) — List print jobs.
- [`POST /api/v1/printing/print-jobs`](/api/printing/create-print-job) — Record a print job.

## Ops

Changelog entries and manager approvals.

- [`GET /api/v1/changelog`](/api/ops/list-changelog) — List the published changelog.
- [`POST /api/v1/changelog`](/api/ops/create-changelog) — Publish a changelog entry.
- [`GET /api/v1/approvals`](/api/ops/list-approvals) — List manager approvals.
- [`POST /api/v1/approvals`](/api/ops/create-approval) — Request a manager approval.
- [`PUT /api/v1/approvals/{approvalId}`](/api/ops/decide-approval) — Approve or reject an approval.

## Dispensing

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

- [`GET /api/v1/dispensing/will-call`](/api/dispensing/list-will-call) — List the will-call queue.
- [`POST /api/v1/dispensing/will-call`](/api/dispensing/create-will-call) — Add a will-call pickup.
- [`PUT /api/v1/dispensing/will-call/{willCallId}/pickup`](/api/dispensing/pickup-will-call) — Collect a will-call pickup.
- [`GET /api/v1/dispensing/generic-search`](/api/dispensing/search-generic-medicines) — Search medicines by generic name.
- [`GET /api/v1/dispensing/refills`](/api/dispensing/list-refill-reminders) — List pending refill reminders.
- [`POST /api/v1/dispensing/refills`](/api/dispensing/create-refill-reminder) — Create a refill reminder.

## SupplierFinance

Supplier invoices, payments, reorder suggestions, and quarantine.

- [`GET /api/v1/supplier-finance/invoices`](/api/supplierfinance/list-supplier-invoices) — List supplier invoices.
- [`POST /api/v1/supplier-finance/invoices`](/api/supplierfinance/create-supplier-invoice) — Record a supplier invoice.
- [`POST /api/v1/supplier-finance/invoices/{invoiceId}/payments`](/api/supplierfinance/record-supplier-invoice-payment) — Record a payment on an invoice.
- [`GET /api/v1/supplier-finance/reorder-suggestions`](/api/supplierfinance/list-reorder-suggestions) — List reorder suggestions.
- [`POST /api/v1/supplier-finance/batches/{batchId}/quarantine`](/api/supplierfinance/set-batch-quarantine) — Quarantine or release a batch.

## Compliance

Statutory books, the EFRIS preview, and devices.

- [`GET /api/v1/compliance/prescription-book`](/api/compliance/list-prescription-book) — List the prescription book.
- [`GET /api/v1/compliance/classified-drugs-book`](/api/compliance/list-classified-drugs-book) — List the classified drugs book.
- [`GET /api/v1/compliance/efris-preview/{saleId}`](/api/compliance/get-efris-preview) — Preview the EFRIS payload for a sale.
- [`GET /api/v1/compliance/devices`](/api/compliance/list-devices) — List registered devices.
- [`POST /api/v1/compliance/devices/{deviceId}/revoke`](/api/compliance/revoke-device) — Revoke a device.
- [`POST /api/v1/compliance/devices/{deviceId}/restore`](/api/compliance/restore-device) — Restore a revoked device.

## Marketing

Public marketing contact and enquiry endpoints.

- [`POST /api/v1/marketing/contact`](/api/marketing/create-marketing-contact) — Record a marketing enquiry.

## Images

Presigned uploads for medicine photos and branding.

- [`POST /api/v1/images/medicines/upload-url`](/api/images/create-medicine-upload-url) — Create a medicine photo upload URL.
- [`POST /api/v1/images/medicines/{medicineId}/image`](/api/images/set-medicine-image) — Attach an uploaded photo to a medicine.
- [`POST /api/v1/images/branding/upload-url`](/api/images/create-branding-upload-url) — Create a branding logo upload URL.
- [`PUT /api/v1/images/branding/logo`](/api/images/set-brand-logo) — Set the organisation logo.