Vendors API

Base route: /api/vendors
Auth required: ✅ JWT Bearer

---

GET /api/vendors

Returns a paginated, filtered list of vendors.

Permission: Vendor:Read

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number (1-based)
pageSize	int	10	Items per page (max 100)
search	string	—	Partial name match (case-insensitive)
vendorType	string	—	Filter by type: Manufacturer | Wholesaler | Agency | Dealer | Pharmacy
isActive	bool	true	true = active vendors, false = soft-deleted (admin only)
sortBy	string	name	Sort field: name | vendorType | outstandingBalance
sortDir	string	asc	Sort direction: asc | desc

WARNING

Passing isActive=false requires is_admin = "true" in the JWT — returns 403 Forbidden otherwise.

Response 200 OK

{
  "items": [
    {
      "id": 1,
      "name": "ABC Pharmaceuticals",
      "address": "123 MG Road, Mumbai",
      "phone": "+91 98765 43210",
      "email": "contact@abcpharma.com",
      "vendorType": "Manufacturer",
      "drugLicenseNumber1": "MH-12345",
      "drugLicenseNumber2": "",
      "additionalDrugLicenseNumbers": [],
      "isActive": true,
      "outstandingBalance": 45000.00,
      "totalInvoiceValue": 120000.00,
      "totalPaidAmount": 75000.00,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-01T14:30:00Z"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 10
}

---

GET /api/vendors/:id

Returns a single vendor with all computed financial totals.

Permission: Vendor:Read

Response 200 OK — VendorDto

Response 404 Not Found

---

POST /api/vendors

Creates a new vendor.

Permission: Vendor:Create

Request Body

{
  "name": "XYZ Wholesalers",
  "address": "456 Link Road, Delhi",
  "phone": "+91 98000 00001",
  "email": "xyz@wholesalers.com",
  "vendorType": "Wholesaler",
  "drugLicenseNumber1": "DL-67890",
  "drugLicenseNumber2": "",
  "additionalDrugLicenseNumbers": []
}

Field	Required	Description
name	✅	Display name
vendorType	✅	Must be one of the valid VendorType values (not OwnPharmacy)
address	—	Physical address
phone	—	Contact number
email	—	Contact email
drugLicenseNumber1	—	Primary drug license
drugLicenseNumber2	—	Secondary drug license
additionalDrugLicenseNumbers	—	Array of extra license strings

Response — Created 201 — VendorDto

---

PUT /api/vendors/:id

Updates an existing vendor.

Permission: Vendor:Update

Response — Updated 200 OK — Updated VendorDto

Response — Not Found 404

---

DELETE /api/vendors/:id

Soft-deletes a vendor (sets isActive = false). Invoices and transactions are preserved.

Permission: Vendor:Delete

Request Body (optional)

{ "reason": "Vendor stopped operations" }

Response — Deleted 204 No Content

Response — Not Found 404

---

VendorType Values

Value	Description
Manufacturer	Produces pharmaceutical products
Wholesaler	Bulk distributor
Agency	Authorised sales agent
Dealer	Local reseller
Pharmacy	Another pharmacy
OwnPharmacy	Your own pharmacy — only one allowed, created during onboarding