> For the complete documentation index, see [llms.txt](https://qbits-organization.gitbook.io/buildwise-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qbits-organization.gitbook.io/buildwise-doc/vendor-management-api.md). # Vendor Management API ### Create Vendor Creates a new vendor for the specified organisation. The authenticated user must have the OWNER or ADMIN role in the organisation. #### Endpoint ``` POST /api/v1/vendors/organisation/{organisationId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier where the vendor will be created #### Request Body ```json { "name": "ABC Construction Materials", "description": "Leading supplier of construction materials and equipment", "address": "123 Industrial Avenue, Construction City, CC 12345", "officePhone": "+1-555-0123", "tin": "12-3456789", "email": "contact@abcmaterials.com", "vendorType": "SUPPLIER", "bankDetails": { "bankName": "First National Bank", "accountNumber": "1234567890", "routingNumber": "987654321", "accountHolderName": "ABC Construction Materials Ltd" } } ``` #### Validation Rules * `name`: Required, cannot be blank, must be unique within the organisation * `description`: Optional * `address`: Required, must be unique within the organisation * `officePhone`: Optional * `tin`: Required, must be unique within the organisation * `email`: Required, must be unique within the organisation * `vendorType`: Required * `bankDetails`: Optional * The authenticated user must have the OWNER or ADMIN role in the organisation #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Vendor created successfully", "action_time": "2025-06-11T14:30:15.123456", "data": { "vendorId": "123e4567-e89b-12d3-a456-426614174000", "name": "ABC Construction Materials", "description": "Leading supplier of construction materials and equipment", "address": "123 Industrial Avenue, Construction City, CC 12345", "officePhone": "+1-555-0123", "tin": "12-3456789", "email": "contact@abcmaterials.com", "vendorType": "SUPPLIER", "isActive": true, "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T14:30:15.123456", "bankDetails": { "bankName": "First National Bank", "accountNumber": "1234567890", "routingNumber": "987654321", "accountHolderName": "ABC Construction Materials Ltd" } } } ``` #### Error Responses * **404** - Organisation not found, member not found in organisation, insufficient permissions, or duplicate vendor data (name, address, TIN, or email already exists) * **400** - Missing required fields or invalid data provided * **401** - Unauthorized (invalid token) * **500** - An unexpected error occurred while creating the vendor *** ### Get Vendor By ID Retrieves a vendor by its ID. The authenticated user must be an active member (OWNER, ADMIN, or MEMBER) of the vendor's organisation. #### Endpoint ``` GET /api/v1/vendors/{vendorId} ``` #### Path Parameters * `vendorId` (UUID) - The vendor identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Vendor retrieved successfully", "action_time": "2025-06-11T14:35:20.654321", "data": { "vendorId": "123e4567-e89b-12d3-a456-426614174000", "name": "ABC Construction Materials", "description": "Leading supplier of construction materials and equipment", "address": "123 Industrial Avenue, Construction City, CC 12345", "officePhone": "+1-555-0123", "tin": "12-3456789", "email": "contact@abcmaterials.com", "vendorType": "SUPPLIER", "isActive": true, "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T14:30:15.123456", "bankDetails": { "bankName": "First National Bank", "accountNumber": "1234567890", "routingNumber": "987654321", "accountHolderName": "ABC Construction Materials Ltd" } } } ``` #### Error Responses * **404** - Vendor not found, member not found in organisation, or insufficient permissions * **401** - Unauthorized *** ### Get All Vendors Retrieves all active vendors for an organisation. The authenticated user must be an active member (OWNER, ADMIN, or MEMBER) of the organisation. #### Endpoint ``` GET /api/v1/vendors/organisation/{organisationId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Vendors retrieved successfully", "action_time": "2025-06-11T15:15:45.234567", "data": [ { "vendorId": "123e4567-e89b-12d3-a456-426614174000", "name": "ABC Construction Materials", "description": "Leading supplier of construction materials and equipment", "address": "123 Industrial Avenue, Construction City, CC 12345", "officePhone": "+1-555-0123", "tin": "12-3456789", "email": "contact@abcmaterials.com", "vendorType": "SUPPLIER", "isActive": true, "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T14:30:15.123456", "bankDetails": { "bankName": "First National Bank", "accountNumber": "1234567890", "routingNumber": "987654321", "accountHolderName": "ABC Construction Materials Ltd" } } ] } ``` #### Error Responses * **404** - Organisation not found, member not found in organisation, or insufficient permissions * **401** - Unauthorized *** ### Update Vendor Updates an existing vendor's details. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` PUT /api/v1/vendors/{vendorId} ``` #### Path Parameters * `vendorId` (UUID) - The vendor identifier to update #### Request Body ```json { "name": "Updated Vendor Name", "description": "Updated vendor description", "address": "456 New Street, Updated City, UC 67890", "officePhone": "+1-555-9876", "tin": "98-7654321", "email": "updated@vendor.com", "vendorType": "CONTRACTOR", "isActive": true, "bankDetails": { "bankName": "Updated Bank", "accountNumber": "0987654321", "routingNumber": "123456789", "accountHolderName": "Updated Vendor Ltd" } } ``` #### Update Rules * Only the provided fields are updated * Empty or null values preserve existing data * Only OWNER or ADMIN members can update vendors * Name must be unique within the organisation if changed #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Vendor updated successfully", "action_time": "2025-06-11T15:00:25.345678", "data": { "vendorId": "123e4567-e89b-12d3-a456-426614174000", "name": "Updated Vendor Name", "description": "Updated vendor description", "address": "456 New Street, Updated City, UC 67890", "officePhone": "+1-555-9876", "tin": "98-7654321", "email": "updated@vendor.com", "vendorType": "CONTRACTOR", "isActive": true, "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T15:00:25.345678", "bankDetails": { "bankName": "Updated Bank", "accountNumber": "0987654321", "routingNumber": "123456789", "accountHolderName": "Updated Vendor Ltd" } } } ``` #### Error Responses * **404** - Vendor not found, member not found in organisation, or insufficient permissions * **403** - Access denied (insufficient permissions) * **400** - Missing required fields, invalid data provided, or duplicate data * **401** - Unauthorized * **500** - An unexpected error occurred while updating the vendor *** ### Delete Vendor Soft deletes a vendor by marking it as inactive. The authenticated user must have OWNER or ADMIN role in the organisation. #### Endpoint ``` DELETE /api/v1/vendors/{vendorId} ``` #### Path Parameters * `vendorId` (UUID) - The vendor identifier to delete #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Vendor deleted successfully", "action_time": "2025-06-11T15:10:30.789123", "data": null } ``` #### Error Responses * **404** - Vendor not found or insufficient permissions * **403** - Access denied (insufficient permissions) * **401** - Unauthorized * **500** - Failed to delete vendor *** ### Authentication & Authorization #### General Rules * All endpoints require authentication via a JWT token * Users must be active members of the relevant organisation * Vendor creation, updates, and deletion require the OWNER or ADMIN role * Vendor retrieval requires any active membership (OWNER, ADMIN, or MEMBER) #### Common Error Responses All endpoints may return: * **401 Unauthorized** - Invalid or missing authentication token * **500 Internal Server Error** - Unexpected server error #### Response Format All successful responses follow this structure: ```json { "success": true, "httpStatus": "OK", "message": "Description of the operation", "action_time": "2025-06-11T15:45:30.123456", "data": { /* Response data or null */ } } ``` ### Additional Notes #### Vendor Types Vendors can have different types, such as: * SUPPLIER * CONTRACTOR * SERVICE\_PROVIDER * CONSULTANT #### Bank Details Bank details are optional and can include: * Bank name * Account number * Routing number * Account holder name #### Soft Delete When a vendor is deleted, it is soft deleted by setting `isActive` to `false`. The vendor record remains in the database but is filtered out from active vendor listings. #### Duplicate Prevention The system prevents duplicate vendors within an organisation based on: * Name (case-insensitive) * Address (case-insensitive) * TIN (case-insensitive) * Email (case-insensitive)