Loans API - Invenicum

Overview

The Loans API manages the lending and tracking of inventory items. It supports loan creation, status management, automatic stock adjustments, and return processing. All loan operations are automatically associated with the authenticated user via JWT token.

Endpoints

Get All Loans

Retrieves all loans across all containers for the authenticated user (Dashboard view).

GET /loans

Authentication

The backend automatically filters loans by the userId extracted from the JWT token.

Response

Loan[]

Array of loan objects

Show Loan Object

integer

Unique identifier for the loan

integer

ID of the container the item belongs to

integer

ID of the inventory item being loaned

string

Name of the loaned item

integer

Number of units loaned (default: 1)

string

Name of the person borrowing the item

string

Email address of the borrower

string

Phone number of the borrower

string

Date when the loan was created (ISO 8601 date)

string

Expected return date (ISO 8601 date)

string

Actual return date when item was returned (ISO 8601 date)

string

Additional notes about the loan

string

Current status: ‘active’ or ‘returned’

integer

ID of the user who created the loan

Example Request

const response = await fetch('/loans', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const loans = await response.json();

Example Response

[
  {
    "id": 1,
    "containerId": 42,
    "inventoryItemId": 15,
    "itemName": "Laptop Dell XPS 15",
    "quantity": 1,
    "borrowerName": "John Doe",
    "borrowerEmail": "john@example.com",
    "borrowerPhone": "+1234567890",
    "loanDate": "2026-03-01",
    "expectedReturnDate": "2026-03-15",
    "actualReturnDate": null,
    "notes": "For presentation at tech conference",
    "status": "active",
    "userId": 7
  }
]

Get Container Loans

Retrieves all loans for a specific container.

GET /containers/{containerId}/loans

Path Parameters

integer

required

The ID of the container whose loans to retrieve

Response

Loan[]

Array of loan objects (same structure as Get All Loans)

Example Request

const response = await fetch('/containers/42/loans', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const loans = await response.json();

Create Loan

Creates a new loan record and automatically decrements the inventory item stock.

POST /containers/{containerId}/loans

Path Parameters

integer

required

The ID of the container containing the inventory item

Request Body

integer

required

ID of the inventory item to loan

string

required

Name of the item being loaned

integer

default:"1"

Number of units to loan

string

Name of the person borrowing the item

string

Email address of the borrower

string

Phone number of the borrower

string

required

Date of the loan (YYYY-MM-DD)

string

Expected return date (YYYY-MM-DD)

string

Additional notes about the loan

string

default:"active"

Initial status (typically ‘active’)

Response

Loan

The newly created loan object

Example Request

const response = await fetch('/containers/42/loans', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inventoryItemId: 15,
    itemName: 'Laptop Dell XPS 15',
    quantity: 1,
    borrowerName: 'John Doe',
    borrowerEmail: 'john@example.com',
    borrowerPhone: '+1234567890',
    loanDate: '2026-03-01',
    expectedReturnDate: '2026-03-15',
    notes: 'For presentation at tech conference',
    status: 'active'
  })
});

const loan = await response.json();

Example Response

{
  "id": 1,
  "containerId": 42,
  "inventoryItemId": 15,
  "itemName": "Laptop Dell XPS 15",
  "quantity": 1,
  "borrowerName": "John Doe",
  "borrowerEmail": "john@example.com",
  "borrowerPhone": "+1234567890",
  "loanDate": "2026-03-01",
  "expectedReturnDate": "2026-03-15",
  "actualReturnDate": null,
  "notes": "For presentation at tech conference",
  "status": "active",
  "userId": 7
}

Error Responses

success

Loan created successfully

error

Bad request - Insufficient stock or invalid inventory item

error

Unauthorized - Authentication required

Return Loan

Marks a loan as returned and automatically increments the inventory item stock.

PUT /containers/{containerId}/loans/{loanId}/return

Path Parameters

integer

required

The ID of the container

integer

required

The ID of the loan to mark as returned

Response

Loan

The updated loan object with status ‘returned’ and actualReturnDate populated

Example Request

const response = await fetch('/containers/42/loans/1/return', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const returnedLoan = await response.json();

Example Response

{
  "id": 1,
  "containerId": 42,
  "inventoryItemId": 15,
  "itemName": "Laptop Dell XPS 15",
  "quantity": 1,
  "borrowerName": "John Doe",
  "borrowerEmail": "john@example.com",
  "borrowerPhone": "+1234567890",
  "loanDate": "2026-03-01",
  "expectedReturnDate": "2026-03-15",
  "actualReturnDate": "2026-03-07",
  "notes": "For presentation at tech conference",
  "status": "returned",
  "userId": 7
}

Error Responses

success

Loan returned successfully

error

Bad request - Loan already returned

error

Loan not found

Delete Loan

Deletes a loan record. Only the loan creator can delete their own loans.

DELETE /containers/{containerId}/loans/{loanId}

Path Parameters

integer

required

The ID of the container

integer

required

The ID of the loan to delete

Response

Returns status code 200 or 204 on successful deletion.

Example Request

const response = await fetch('/containers/42/loans/1', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.ok) {
  console.log('Loan deleted successfully');
}

Error Responses

success

Loan deleted successfully

success

Loan deleted successfully (no content)

error

Forbidden - You can only delete your own loans

error

Loan not found

Get Loan Statistics

Retrieves statistical summary of loans for a container.

GET /containers/{containerId}/loans-stats

Path Parameters

integer

required

The ID of the container

Response

integer

Total number of loans (all statuses)

integer

Number of currently active loans

integer

Number of active loans past their expected return date

integer

Number of returned loans

Example Request

const response = await fetch('/containers/42/loans-stats', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const stats = await response.json();

Example Response

{
  "totalLoans": 45,
  "activeLoans": 12,
  "overdueLoans": 3,
  "returnedLoans": 33
}

Business Logic Notes

Automatic Stock Management

Creating a loan automatically decrements the inventory item’s stock by the loan quantity
Returning a loan (via the return endpoint) automatically increments the stock back
The backend enforces stock validation - loans cannot exceed available quantity

User Authentication

The userId field is automatically populated from the JWT token during loan creation
Users cannot specify their own userId in the request body
Only loan owners can delete their loans

Status Management

Loans are created with status ‘active’
The return endpoint sets status to ‘returned’ and populates actualReturnDate
Status transitions are enforced server-side

Overdue Detection

The isOverdue computed property returns true if:
- Status is ‘active’ AND
- expectedReturnDate exists AND
- Current date is after expectedReturnDate
Use this for UI indicators and alert generation

Voucher IDs

Each loan has a formatted voucher ID: V-000001, V-000042, etc.
Generated via formattedVoucherId getter: pads loan ID to 6 digits
Useful for printing and reference

Date Handling

All dates are stored and transmitted in ISO 8601 format (YYYY-MM-DD)
The toJson() method automatically formats dates to local timezone
Client should parse dates using DateTime.parse()

Data Integrity

Deleting a loan does not automatically restore inventory stock
Consider implementing soft deletes for audit trails
Loan history is valuable for analytics and reporting

​Overview

​Endpoints

​Get All Loans

​Authentication

​Response

​Example Request

​Example Response

​Get Container Loans

​Path Parameters

​Response

​Example Request

​Create Loan

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Return Loan

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Delete Loan

​Path Parameters

​Response

​Example Request

​Error Responses

​Get Loan Statistics

​Path Parameters

​Response

​Example Request

​Example Response

​Business Logic Notes

​Automatic Stock Management

​User Authentication

​Status Management

​Overdue Detection

​Voucher IDs

​Date Handling

​Data Integrity

Overview

Endpoints

Get All Loans

Authentication

Response

Example Request

Example Response

Get Container Loans

Path Parameters

Response

Example Request

Create Loan

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Return Loan

Path Parameters

Response

Example Request

Example Response

Error Responses

Delete Loan

Path Parameters

Response

Example Request

Error Responses

Get Loan Statistics

Path Parameters

Response

Example Request

Example Response

Business Logic Notes

Automatic Stock Management

User Authentication

Status Management

Overdue Detection

Voucher IDs

Date Handling

Data Integrity