Expenses API Reference

Manage expenses including listing, creation, editing, viewing, and deleting.

 API Reference: Swagger Documentation

Authentication

All endpoints require a Bearer token.

Headers

Authorization: Bearer <your_token>
Content-Type: application/json

1. List Expenses

GET /{db}/api/expenses

Returns a paginated list of expenses. Supports filtering by search query, page size, and page number.

Query Parameters

Example Response

[
  {
    "id": "E12345",
    "cc": "EXP-001",
    "name": "Office Supplies",
    "documentNo": "DOC-2025-01",
    "documentDate": "2025-01-10",
    "amount": 120.50,
    "status": "approved",
    "expenseType": "general",
    "created": "2025-01-10T08:00:00Z",
    "updated": "2025-01-12T15:30:00Z"
  }
]

2. Create Expense

POST /{db}/api/expenses

Creates a new expense.

Request Body (ExpenseCreateRequest)

ExpenseLineCreate

• description* (string)
• quantity (number)
• unitPrice (number)
• amount* (number)
• accountId (string)

Example Request

{
  "name": "Travel Expense",
  "documentDate": "2025-02-01",
  "amount": 500,
  "expenseType": "travel",
  "vendorId": "V123",
  "currencyId": "EUR",
  "operationCenterId": "OC1",
  "lines": [
    {
      "description": "Flight ticket",
      "quantity": 1,
      "unitPrice": 500,
      "amount": 500,
      "accountId": "ACC-01"
    }
  ]
}

Example Response

{
  "entity": {
    "id": "E67890",
    "cc": "EXP-002",
    "name": "Travel Expense",
    "documentNo": "DOC-2025-02",
    "documentDate": "2025-02-01",
    "amount": 500,
    "status": "draft",
    "expenseType": "travel",
    "created": "2025-02-01T10:00:00Z"
  }
}

3. View Expense

GET /{db}/api/expenses/{id}

Retrieves a single expense by its code.

Example Response (ExpenseDetail)

{
  "id": "E12345",
  "cc": "EXP-001",
  "name": "Office Supplies",
  "documentNo": "DOC-2025-01",
  "documentDate": "2025-01-10",
  "amount": 120.50,
  "status": "approved",
  "expenseType": "general",
  "created": "2025-01-10T08:00:00Z",
  "updated": "2025-01-12T15:30:00Z",
  "lines": [
    {
      "id": "L1",
      "description": "Printer Paper",
      "quantity": 10,
      "unitPrice": 12.05,
      "amount": 120.50,
      "accountId": "ACC-02"
    }
  ],
  "vendor": {
    "id": "V123",
    "name": "Paper & Co",
    "email": "info@paperco.com"
  },
  "currency": {
    "id": "EUR",
    "code": "EUR",
    "name": "Euro"
  },
  "operationCenter": {
    "id": "OC1",
    "name": "Head Office",
    "code": "HO"
  }
}

4. Update Expense

PUT /{db}/api/expenses/{id}

Updates an existing expense.

Request Body (ExpenseUpdateRequest)

Fields same as ExpenseCreateRequest, but all optional.
Supports ExpenseLineUpdate objects for updating lines.

Example Request

{
  "name": "Office Supplies Updated",
  "amount": 150.00,
  "expenseType": "general"
}

Example Response

{
  "entity": {
    "id": "E12345",
    "cc": "EXP-001",
    "name": "Office Supplies Updated",
    "documentNo": "DOC-2025-01",
    "amount": 150.00,
    "status": "approved",
    "updated": "2025-01-13T11:00:00Z"
  }
}

5. Delete Expense

DELETE /{db}/api/expenses/{id}

Deletes an expense by its code.

Example Response

{
  "success": "Expense deleted successfully"
}

Get Operation Centers

Endpoint

GET /{db}/api/operation-centers/expense

Description
Retrieve a list of operation centers available for expense allocation.

Parameters

• None

Sample Request

GET /{db}/api/operation-centers/expense

Sample Response

[
  {
    "id": 1,
    "name": "Main Office",
    "code": "OC-001"
  },
  {
    "id": 2,
    "name": "Branch Office",
    "code": "OC-002"
  }
]

Get Currency Rates

Endpoint

POST /{db}/api/currency-rates/settings/currency/currency_rate

Description
Fetch currency exchange rates used in expense entries.

Parameters

• None in query.
• Request body may include currency or date filter (optional).

Sample Request

POST /{db}/api/currency-rates/settings/currency/currency_rate
Content-Type: application/json

{
  "currency": "USD",
  "date": "2025-08-19"
}

Sample Response

{
  "currency": "USD",
  "base": "ETB",
  "rate": 115.25,
  "date": "2025-08-19"
}

Get Vendors

Endpoint

GET /{db}/api/get/all/accounts/isSupplier

Description
Retrieve all accounts that are marked as suppliers (vendors).

Parameters

• None

Sample Request

GET /{db}/api/get/all/accounts/isSupplier

Sample Response

[
  {
    "id": 101,
    "name": "Global Supplies Ltd",
    "vat": "ET123456789",
    "status": "active"
  },
  {
    "id": 102,
    "name": "Tech Importers",
    "vat": "ET987654321",
    "status": "active"
  }
]

Get Expense Details

Endpoint

POST /{db}/api/grid/filters/forms/search/expense-details

Query Parameters

• startDate (string, required) – Filter from date (YYYY-MM-DD HH:mm:ss).
• endDate (string, required) – Filter to date (YYYY-MM-DD HH:mm:ss).

Description
Search and filter expense records within the provided date range.

Sample Request

POST /{db}/api/grid/filters/forms/search/expense-details?startDate=2025-05-20&endDate=2025-08-20%2023:59:59
Content-Type: application/json

{
  "filters": {
    "status": "approved"
  }
}

Sample Response

[
  {
    "id": 2001,
    "vendor": "Global Supplies Ltd",
    "amount": 4500,
    "currency": "ETB",
    "status": "approved",
    "date": "2025-06-05"
  },
  {
    "id": 2002,
    "vendor": "Tech Importers",
    "amount": 1200,
    "currency": "USD",
    "status": "pending",
    "date": "2025-07-10"
  }
]