> 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.md).

# Accounting

## Chart of Accounts 

### Get the Organisation Chart of Accounts

The hierarchical chart of accounts for a specified organisation is retrieved,  grouped by account type. The authenticated user must be an active member of the organisation.

#### Endpoint

```
GET /api/v1/accounting/chart-of-accounts/organisation/{organisationId}
```

#### Path Parameters

* `organisationId` (UUID) - The organisation identifier for which to retrieve the chart of accounts

#### Access Requirements

* User must be authenticated with a valid JWT token
* User must be an active member of the organisation
* Organisation owner always has access
* Organisation members with ACTIVE status have access

#### Success Response

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Chart of accounts retrieved successfully",
  "action_time": "2025-06-14T10:30:15.123456",
  "data": {
    "organisationId": "987fcdeb-51a2-43d1-9f12-123456789abc",
    "organisationName": "ABC Construction Company",
    "accountGroups": {
      "ASSETS": {
        "groupName": "Assets",
        "totalAccounts": 13,
        "accounts": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "accountCode": "1000",
            "accountName": "Current Assets",
            "accountType": "ASSETS",
            "isParent": true,
            "parentAccountId": null,
            "level": 0,
            "children": [
              {
                "id": "234f5678-f90c-23e4-b567-537725285111",
                "accountCode": "1010",
                "accountName": "Cash and Cash Equivalents",
                "accountType": "ASSETS",
                "isParent": false,
                "parentAccountId": "123e4567-e89b-12d3-a456-426614174000",
                "level": 1,
                "children": []
              },
              {
                "id": "345g6789-g01d-34f5-c678-648836396222",
                "accountCode": "1020",
                "accountName": "Accounts Receivable",
                "accountType": "ASSETS",
                "isParent": false,
                "parentAccountId": "123e4567-e89b-12d3-a456-426614174000",
                "level": 1,
                "children": []
              },
              {
                "id": "456h7890-h12e-45g6-d789-759947407333",
                "accountCode": "1100",
                "accountName": "Inventory - Raw Materials",
                "accountType": "ASSETS",
                "isParent": false,
                "parentAccountId": "123e4567-e89b-12d3-a456-426614174000",
                "level": 1,
                "children": []
              }
            ]
          },
          {
            "id": "567i8901-i23f-56h7-e890-860058518444",
            "accountCode": "1500",
            "accountName": "Fixed Assets",
            "accountType": "ASSETS",
            "isParent": true,
            "parentAccountId": null,
            "level": 0,
            "children": [
              {
                "id": "678j9012-j34g-67i8-f901-971169629555",
                "accountCode": "1510",
                "accountName": "Construction Equipment",
                "accountType": "ASSETS",
                "isParent": false,
                "parentAccountId": "567i8901-i23f-56h7-e890-860058518444",
                "level": 1,
                "children": []
              },
              {
                "id": "789k0123-k45h-78j9-g012-082270730666",
                "accountCode": "1520",
                "accountName": "Vehicles",
                "accountType": "ASSETS",
                "isParent": false,
                "parentAccountId": "567i8901-i23f-56h7-e890-860058518444",
                "level": 1,
                "children": []
              }
            ]
          }
        ]
      },
      "LIABILITIES": {
        "groupName": "Liabilities",
        "totalAccounts": 8,
        "accounts": [
          {
            "id": "890l1234-l56i-89k0-h123-193381841777",
            "accountCode": "2000",
            "accountName": "Current Liabilities",
            "accountType": "LIABILITIES",
            "isParent": true,
            "parentAccountId": null,
            "level": 0,
            "children": [
              {
                "id": "901m2345-m67j-90l1-i234-204492952888",
                "accountCode": "2010",
                "accountName": "Accounts Payable",
                "accountType": "LIABILITIES",
                "isParent": false,
                "parentAccountId": "890l1234-l56i-89k0-h123-193381841777",
                "level": 1,
                "children": []
              },
              {
                "id": "012n3456-n78k-01m2-j345-315503063999",
                "accountCode": "2020",
                "accountName": "Accrued Expenses",
                "accountType": "LIABILITIES",
                "isParent": false,
                "parentAccountId": "890l1234-l56i-89k0-h123-193381841777",
                "level": 1,
                "children": []
              }
            ]
          }
        ]
      },
      "EQUITY": {
        "groupName": "Equity",
        "totalAccounts": 3,
        "accounts": [
          {
            "id": "123o4567-o89l-12n3-k456-426614174000",
            "accountCode": "3000",
            "accountName": "Owner's Equity",
            "accountType": "EQUITY",
            "isParent": false,
            "parentAccountId": null,
            "level": 0,
            "children": []
          }
        ]
      },
      "REVENUE": {
        "groupName": "Revenue",
        "totalAccounts": 5,
        "accounts": [
          {
            "id": "234p5678-p90m-23o4-l567-537725285111",
            "accountCode": "4000",
            "accountName": "Construction Revenue",
            "accountType": "REVENUE",
            "isParent": false,
            "parentAccountId": null,
            "level": 0,
            "children": []
          }
        ]
      },
      "EXPENSES": {
        "groupName": "Expenses",
        "totalAccounts": 15,
        "accounts": [
          {
            "id": "345q6789-q01n-34p5-m678-648836396222",
            "accountCode": "5000",
            "accountName": "Direct Costs",
            "accountType": "EXPENSES",
            "isParent": true,
            "parentAccountId": null,
            "level": 0,
            "children": [
              {
                "id": "456r7890-r12o-45q6-n789-759947407333",
                "accountCode": "5010",
                "accountName": "Materials",
                "accountType": "EXPENSES",
                "isParent": false,
                "parentAccountId": "345q6789-q01n-34p5-m678-648836396222",
                "level": 1,
                "children": []
              },
              {
                "id": "567s8901-s23p-56r7-o890-860058518444",
                "accountCode": "5100",
                "accountName": "Labour",
                "accountType": "EXPENSES",
                "isParent": false,
                "parentAccountId": "345q6789-q01n-34p5-m678-648836396222",
                "level": 1,
                "children": []
              }
            ]
          }
        ]
      }
    },
    "totalAccounts": 44,
    "generatedAt": "2025-06-14T10:30:15.123456"
  }
}
```

#### Response Structure

**Main Response Object**

* `organisationId` (UUID) - The organisation identifier
* `organisationName` (string) - The name of the organisation
* `accountGroups` (object) - Chart of accounts grouped by account type
* `totalAccounts` (integer) - Total number of accounts across all groups
* `generatedAt` (datetime) - Timestamp when the response was generated

**Account Groups**

The `accountGroups` object contains the following account types:

* `ASSETS` - Asset accounts (cash, receivables, inventory, equipment, etc.)
* `LIABILITIES` - Liability accounts (payables, loans, accrued expenses, etc.)
* `EQUITY` - Equity accounts (owner's equity, retained earnings, etc.)
* `REVENUE` - Revenue accounts (construction revenue, service revenue, etc.)
* `EXPENSES` - Expense accounts (materials, labour, overhead, etc.)

#### Error Responses

* **404: Organisation not found or No accounts found for organisation**
* **403:  User is not a member of this organisation, or User Membership is not active**
* **401: User is not authenticated**
* **500: An unexpected error occurred while retrieving the chart of accounts**

### Authentication & Authorization

#### Access Control Rules

* **Authentication Required**: All endpoints require a valid JWT token
* **Organisation Membership**: The User must be an active member of the organisation
* **Owner Access**: Organisation owners always have full access
* **Member Access**: Organisation members with ACTIVE status can view chart of ac