> 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/accounting/transaction/business-document-document-flow/voucher.md).

# Voucher

### Overview

This API provides endpoints for managing vouchers within an organisation. Vouchers are financial documents used to track payments to vendors for specific projects. The API supports creating, retrieving, updating, approving, and previewing voucher numbers, as well as retrieving vouchers by project or organisation. All endpoints require authentication via a JWT token, and users must have appropriate roles to perform operations.

### Endpoints

#### Create Voucher

Creates a new voucher for the specified organisation. The authenticated user must have the **ACCOUNTANT**, **OWNER**, or **PROJECT\_MANAGER** role in the project.

**Endpoint**\
`POST /api/v1/org-accounting/{organisationId}/vouchers`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier where the voucher will be created.

**Request Body**

```json
{
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "voucherDate": "2025-06-14",
  "voucherType": "PAYMENT",
  "paymentMode": "BANK_TRANSFER",
  "overallDescription": "Payment for construction materials",
  "payees": [
    {
      "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
      "amount": 1500.00,
      "description": "Concrete and steel supplies"
    },
    {
      "vendorId": "456e7890-e89b-12d3-a456-426614174111",
      "amount": 2000.00,
      "description": "Labor charges"
    }
  ],
  "attachments": [
    {
      "filename": "receipt.pdf",
      "fileExtension": "pdf",
      "fileHash": "a1b2c3d4e5f6",
      "systemDirectory": "/uploads/vouchers",
      "originalFilename": "vendor_receipt.pdf",
      "fileSize": 102400,
      "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf"
    }
  ]
}
```

**Validation Rules**

* `projectId`: Required, must exist and belong to the organisation.
* `voucherDate`: Required, must be a valid date.
* `voucherType`: Required, valid types include `PAYMENT`, `REIMBURSEMENT`, etc.
* `paymentMode`: Required, valid modes include `BANK_TRANSFER`, `CASH`, etc.
* `payees`: Required, must contain at least one payee.
  * `vendorId`: Required, must exist and belong to the organisation.
  * `amount`: Required, must be a positive number.
* `attachments`: Optional, if provided, must include valid file metadata.
* The authenticated user must have **ACCOUNTANT**, **OWNER**, or **PROJECT\_MANAGER** role in the project.
* User must be an active member of the organisation.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher created successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "voucherNumber": "PROJ0001-VCH-25-001",
    "voucherDate": "2025-06-14T00:00:00",
    "voucherType": "PAYMENT",
    "status": "DRAFT",
    "paymentMode": "BANK_TRANSFER",
    "totalAmount": 3500.00,
    "currency": "TSh",
    "overallDescription": "Payment for construction materials",
    "createdById": "789e0123-e89b-12d3-a456-426614174222",
    "createdByName": "john.doe",
    "organisationId": "789e0123-e89b-12d3-a456-426614174333",
    "organisationName": "BuildWise Construction Ltd",
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "projectName": "Downtown Office Complex",
    "createdAt": "2025-06-14T14:44:30.123456",
    "updatedAt": "2025-06-14T14:44:30.123456",
    "payees": [
      {
        "id": "111e2222-e89b-12d3-a456-426614174333",
        "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
        "vendorName": "ABC Supplies",
        "vendorType": "SUPPLIER",
        "amount": 1500.00,
        "description": "Concrete and steel supplies",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      },
      {
        "id": "222e3333-e89b-12d3-a456-426614174444",
        "vendorId": "456e7890-e89b-12d3-a456-426614174111",
        "vendorName": "XYZ Contractors",
        "vendorType": "CONTRACTOR",
        "amount": 2000.00,
        "description": "Labor charges",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      }
    ],
    "attachments": [
      {
        "id": "333e4444-e89b-12d3-a456-426614174555",
        "filename": "receipt.pdf",
        "fileExtension": "pdf",
        "fileHash": "a1b2c3d4e5f6",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_receipt.pdf",
        "fileSize": 102400,
        "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      }
    ]
  }
}
```

**Error Responses**

* **404**: Organisation not found, project not found, vendor not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **400**: Missing required fields or invalid data provided.
* **401**: Unauthorized (invalid token).
* **500**: An unexpected error occurred while creating the voucher.

#### Preview Voucher Number

Generates a preview of the next voucher number for a specific project without creating a voucher.

**Endpoint**\
`POST /api/v1/org-accounting/{organisationId}/vouchers/preview-voucher-number`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.

**Request Body**

```json
{
  "projectId": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Validation Rules**

* `projectId`: Required, must exist and belong to the organisation.
* The authenticated user must have **OWNER**, **ADMIN**, or **MEMBER** role in the organisation.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher number preview generated successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "nextVoucherNumber": "PROJ0001-VCH-25-002",
    "organisationName": "BuildWise Construction Ltd",
    "projectName": "Downtown Office Complex",
    "projectCode": "PROJ0001"
  }
}
```

**Error Responses**

* **404**: Organisation not found, project not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **401**: Unauthorized (invalid token).
* **400**: Missing required fields or invalid data provided.

***

#### Get Voucher By ID

Retrieves a specific voucher by its ID. The authenticated user must have **OWNER**, **ADMIN**, or **MEMBER** role in the organisation.

**Endpoint**\
`GET /api/v1/org-accounting/{organisationId}/vouchers/{voucherId}`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.
* `voucherId` (UUID): The voucher identifier.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher retrieved successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "voucherNumber": "PROJ0001-VCH-25-001",
    "voucherDate": "2025-06-14T00:00:00",
    "voucherType": "PAYMENT",
    "status": "DRAFT",
    "paymentMode": "BANK_TRANSFER",
    "totalAmount": 3500.00,
    "currency": "TSh",
    "overallDescription": "Payment for construction materials",
    "createdById": "789e0123-e89b-12d3-a456-426614174222",
    "createdByName": "john.doe",
    "organisationId": "789e0123-e89b-12d3-a456-426614174333",
    "organisationName": "BuildWise Construction Ltd",
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "projectName": "Downtown Office Complex",
    "createdAt": "2025-06-14T14:44:30.123456",
    "updatedAt": "2025-06-14T14:44:30.123456",
    "payees": [
      {
        "id": "111e2222-e89b-12d3-a456-426614174333",
        "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
        "vendorName": "ABC Supplies",
        "vendorType": "SUPPLIER",
        "amount": 1500.00,
        "description": "Concrete and steel supplies",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      },
      {
        "id": "222e3333-e89b-12d3-a456-426614174444",
        "vendorId": "456e7890-e89b-12d3-a456-426614174111",
        "vendorName": "XYZ Contractors",
        "vendorType": "CONTRACTOR",
        "amount": 2000.00,
        "description": "Labor charges",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      }
    ],
    "attachments": [
      {
        "id": "333e4444-e89b-12d3-a456-426614174555",
        "filename": "receipt.pdf",
        "fileExtension": "pdf",
        "fileHash": "a1b2c3d4e5f6",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_receipt.pdf",
        "fileSize": 102400,
        "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      }
    ]
  }
}
```

**Error Responses**

* **404**: Voucher not found, organisation not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **401**: Unauthorized (invalid token).

#### Get Voucher By Number

Retrieves a specific voucher by its voucher number. The authenticated user must have **OWNER**, **ADMIN**, or **MEMBER** role in the organisation.

**Endpoint**\
`GET /api/v1/org-accounting/{organisationId}/vouchers/voucher-number/{voucherNumber}`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.
* `voucherNumber` (String): The voucher number (e.g., "PROJ0001-VCH-25-001").

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher retrieved successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "voucherNumber": "PROJ0001-VCH-25-001",
    "voucherDate": "2025-06-14T00:00:00",
    "voucherType": "PAYMENT",
    "status": "DRAFT",
    "paymentMode": "BANK_TRANSFER",
    "totalAmount": 3500.00,
    "currency": "TSh",
    "overallDescription": "Payment for construction materials",
    "createdById": "789e0123-e89b-12d3-a456-426614174222",
    "createdByName": "John Doe",
    "organisationId": "789e0123-e89b-12d3-a456-426614174333",
    "organisationName": "BuildWise Construction Ltd",
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "projectName": "Downtown Office Complex",
    "createdAt": "2025-06-14T14:44:30.123456",
    "updatedAt": "2025-06-14T14:44:30.123456",
    "payees": [
      {
        "id": "111e2222-e89b-12d3-a456-426614174333",
        "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
        "vendorName": "ABC Supplies",
        "vendorType": "SUPPLIER",
        "amount": 1500.00,
        "description": "Concrete and steel supplies",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      },
      {
        "id": "222e3333-e89b-12d3-a456-426614174444",
        "vendorId": "456e7890-e89b-12d3-a456-426614174111",
        "vendorName": "XYZ Contractors",
        "vendorType": "CONTRACTOR",
        "amount": 2000.00,
        "description": "Labor charges",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      }
    ],
    "attachments": [
      {
        "id": "333e4444-e89b-12d3-a456-426614174555",
        "filename": "receipt.pdf",
        "fileExtension": "pdf",
        "fileHash": "a1b2c3d4e5f6",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_receipt.pdf",
        "fileSize": 102400,
        "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      }
    ]
  }
}
```

**Error Responses**

* **404**: Voucher not found, organisation not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **401**: Unauthorized (invalid token).

***

#### Get Project Vouchers

Retrieves all vouchers for a specific project. The authenticated user must have **OWNER**, **ADMIN**, or **MEMBER** role in the organisation.

**Endpoint**\
`GET /api/v1/org-accounting/{organisationId}/vouchers/project/{projectId}`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.
* `projectId` (UUID): The project identifier.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Project vouchers retrieved successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": [
    {
      "voucherId": "456e7890-e89b-12d3-a456-426614174111",
      "voucherNumber": "PROJ0001-VCH-25-001",
      "status": "DRAFT",
      "totalAmount": 3500.00,
      "payeeCount": 2,
      "voucherDate": "2025-06-14T00:00:00",
      "preparedBy": "John Doe",
      "projectName": "Downtown Office Complex"
    },
    {
      "voucherId": "567e8901-e89b-12d3-a456-426614174222",
      "voucherNumber": "PROJ0001-VCH-25-002",
      "status": "APPROVED",
      "totalAmount": 5000.00,
      "payeeCount": 3,
      "voucherDate": "2025-06-13T00:00:00",
      "preparedBy": "Jane Smith",
      "projectName": "Downtown Office Complex"
    }
  ]
}
```

**Error Responses**

* **404**: Project not found, organisation not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **401**: Unauthorized (invalid token).

***

#### Get Organisation Vouchers

Retrieves all vouchers for a specific organisation. The authenticated user must have **OWNER**, **ADMIN**, or **MEMBER** role in the organisation.

**Endpoint**\
`GET /api/v1/org-accounting/{organisationId}/vouchers`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Organisation vouchers retrieved successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": [
    {
      "voucherId": "456e7890-e89b-12d3-a456-426614174111",
      "voucherNumber": "PROJ0001-VCH-25-001",
      "status": "DRAFT",
      "totalAmount": 3500.00,
      "payeeCount": 2,
      "voucherDate": "2025-06-14T00:00:00",
      "preparedBy": "John Doe",
      "projectName": "Downtown Office Complex"
    },
    {
      "voucherId": "678e9012-e89b-12d3-a456-426614174333",
      "voucherNumber": "PROJ0002-VCH-25-001",
      "status": "APPROVED",
      "totalAmount": 7500.00,
      "payeeCount": 4,
      "voucherDate": "2025-06-12T00:00:00",
      "preparedBy": "Jane Smith",
      "projectName": "Residential Complex Phase 1"
    }
  ]
}
```

**Error Responses**

* **404**: Organisation not found or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **401**: Unauthorized (invalid token).

#### Approve Voucher

Approves a specific voucher. The authenticated user must have **OWNER** or **ADMIN** role in the organisation.

**Endpoint**\
`POST /api/v1/org-accounting/{organisationId}/vouchers/{voucherId}/approve`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.
* `voucherId` (UUID): The voucher identifier.

**Request Body**

```json
{
  "approvedBy": "john.doe"
}
```

**Validation Rules**

* `approvedBy`: Required, must be a valid username.
* Voucher must be in **DRAFT** or **PENDING\_APPROVAL** status.
* The authenticated user must have **OWNER** or **ADMIN** role in the organisation.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher approved successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "voucherNumber": "PROJ0001-VCH-25-001",
    "voucherDate": "2025-06-14T00:00:00",
    "voucherType": "PAYMENT",
    "status": "APPROVED",
    "paymentMode": "BANK_TRANSFER",
    "totalAmount": 3500.00,
    "currency": "TSh",
    "overallDescription": "Payment for construction materials",
    "createdById": "789e0123-e89b-12d3-a456-426614174222",
    "createdByName": "john.doe",
    "organisationId": "789e0123-e89b-12d3-a456-426614174333",
    "organisationName": "BuildWise Construction Ltd",
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "projectName": "Downtown Office Complex",
    "createdAt": "2025-06-14T14:44:30.123456",
    "updatedAt": "2025-06-14T14:44:30.123456",
    "payees": [
      {
        "id": "111e2222-e89b-12d3-a456-426614174333",
        "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
        "vendorName": "ABC Supplies",
        "vendorType": "SUPPLIER",
        "amount": 1500.00,
        "description": "Concrete and steel supplies",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      },
      {
        "id": "222e3333-e89b-12d3-a456-426614174444",
        "vendorId": "456e7890-e89b-12d3-a456-426614174111",
        "vendorName": "XYZ Contractors",
        "vendorType": "CONTRACTOR",
        "amount": 2000.00,
        "description": "Labor charges",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      }
    ],
    "attachments": [
      {
        "id": "333e4444-e89b-12d3-a456-426614174555",
        "filename": "receipt.pdf",
        "fileExtension": "pdf",
        "fileHash": "a1b2c3d4e5f6",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_receipt.pdf",
        "fileSize": 102400,
        "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      }
    ]
  }
}
```

**Error Responses**

* **404**: Voucher not found, organisation not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **400**: Voucher not in DRAFT or PENDING\_APPROVAL status, or invalid data provided.
* **401**: Unauthorized (invalid token).

#### Update Voucher

Updates an existing voucher. Only vouchers in **DRAFT** status can be updated. The authenticated user must have **ACCOUNTANT**, **OWNER**, or **PROJECT\_MANAGER** role in the project.

**Endpoint**\
`PUT /api/v1/org-accounting/{organisationId}/vouchers/{voucherId}`

**Path Parameters**

* `organisationId` (UUID): The organisation identifier.
* `voucherId` (UUID): The voucher identifier.

**Request Body**

```json
{
  "voucherDate": "2025-06-15",
  "voucherType": "REIMBURSEMENT",
  "paymentMode": "CASH",
  "overallDescription": "Updated payment for construction materials",
  "payees": [
    {
      "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
      "amount": 2000.00,
      "description": "Updated concrete and steel supplies"
    }
  ],
  "attachmentIdsToKeep": ["333e4444-e89b-12d3-a456-426614174555"],
  "newAttachments": [
    {
      "filename": "invoice.pdf",
      "fileExtension": "pdf",
      "fileHash": "b2c3d4e5f6g7",
      "systemDirectory": "/uploads/vouchers",
      "originalFilename": "vendor_invoice.pdf",
      "fileSize": 204800,
      "filePathUrl": "https://storage.example.com/vouchers/invoice.pdf"
    }
  ]
}
```

**Validation Rules**

* `voucherId`: Required, must exist and belong to the organisation.
* `voucherDate`: Optional, must be a valid date if provided.
* `voucherType`: Optional, must be a valid type if provided.
* `paymentMode`: Optional, must be a valid mode if provided.
* `payees`: Optional, if provided, must contain at least one payee.
  * `vendorId`: Required, must exist and belong to the organisation.
  * `amount`: Required, must be a positive number.
* `attachmentIdsToKeep`: Optional, if provided, must contain valid attachment IDs to retain.
* `newAttachments`: Optional, if provided, must include valid file metadata.
* Voucher must be in **DRAFT** status.
* The authenticated user must have **ACCOUNTANT**, **OWNER**, or **PROJECT\_MANAGER** role in the project.
* User must be an active member of the organisation.

**Success Response**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Voucher updated successfully",
  "action_time": "2025-06-14T14:44:30.123456",
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "voucherNumber": "PROJ0001-VCH-25-001",
    "voucherDate": "2025-06-15T00:00:00",
    "voucherType": "REIMBURSEMENT",
    "status": "DRAFT",
    "paymentMode": "CASH",
    "totalAmount": 2000.00,
    "currency": "TSh",
    "overallDescription": "Updated payment for construction materials",
    "createdById": "789e0123-e89b-12d3-a456-426614174222",
    "createdByName": "john.doe",
    "organisationId": "789e0123-e89b-12d3-a456-426614174333",
    "organisationName": "BuildWise Construction Ltd",
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "projectName": "Downtown Office Complex",
    "createdAt": "2025-06-14T14:44:30.123456",
    "updatedAt": "2025-06-14T14:44:30.123456",
    "payees": [
      {
        "id": "444e5555-e89b-12d3-a456-426614174666",
        "vendorId": "987fcdeb-51a2-43d1-9c4f-123456789abc",
        "vendorName": "ABC Supplies",
        "vendorType": "SUPPLIER",
        "amount": 2000.00,
        "description": "Updated concrete and steel supplies",
        "paymentStatus": "PENDING",
        "paidAt": null,
        "paymentReference": null
      }
    ],
    "attachments": [
      {
        "id": "333e4444-e89b-12d3-a456-426614174555",
        "filename": "receipt.pdf",
        "fileExtension": "pdf",
        "fileHash": "a1b2c3d4e5f6",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_receipt.pdf",
        "fileSize": 102400,
        "filePathUrl": "https://storage.example.com/vouchers/receipt.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      },
      {
        "id": "555e6666-e89b-12d3-a456-426614174777",
        "filename": "invoice.pdf",
        "fileExtension": "pdf",
        "fileHash": "b2c3d4e5f6g7",
        "systemDirectory": "/uploads/vouchers",
        "originalFilename": "vendor_invoice.pdf",
        "fileSize": 204800,
        "filePathUrl": "https://storage.example.com/vouchers/invoice.pdf",
        "uploadedAt": "2025-06-14T14:44:30.123456"
      }
    ]
  }
}
```

**Error Responses**

* **404**: Voucher not found, organisation not found, vendor not found, or insufficient permissions.
* **403**: Access denied (insufficient role permissions).
* **400**: Voucher not in DRAFT status, or invalid data provided.
* **401**: Unauthorized (invalid token).

***

### Additional Notes

#### Voucher Numbering System

Vouchers use a structured numbering format: `[PROJECT-CODE]-VCH-[YEAR]-[ORG-SEQUENCE]`

* **Project Code**: Format like `PROJ0001`, `PROJ0002`, etc.
* **Year**: 2-digit format (e.g., `25` for 2025).
* **Org Sequence**: 3-digit sequential number per organisation (e.g., `001`, `002`, etc.).\
  Example: `PROJ0001-VCH-25-001`

#### Voucher Types

Vouchers can have different types, such as:

* `PAYMENT`
* `REIMBURSEMENT`
* Other types as defined by the system.

#### Payment Modes

Supported payment modes include:

* `BANK_TRANSFER`
* `CASH`
* Other modes as defined by the system.

#### Voucher Status Flow

Vouchers progress through these statuses:

* **DRAFT**: Initial creation state.
* **PENDING\_APPROVAL**: Awaiting approval.
* **APPROVED**: Approved and ready for payment.
* Other statuses may be supported (e.g., `PAID`, `CANCELLED`).

#### Payee Structure

Each voucher payee contains:

* Vendor ID, name, and type.
* Amount and description.
* Payment status (`PENDING`, `PAID`, etc.).
* Payment reference and paid timestamp (if applicable).

#### Attachment Structure

Each voucher attachment contains:

* Filename, extension, and original filename.
* File hash, size, and system directory.
* File path URL and upload timestamp.

#### Currency Support

Vouchers support multiple currencies, with the default set to `TSh` (Tanzanian Shilling) in this implementation.

#### Project Team Validation

The system validates that users have appropriate roles within the project team before allowing voucher operations, ensuring proper access control at the project level.