# InstantCashBackOfficeController API Documentation

## updateApprovalStatus Function

### Purpose
Updates the approval status of a bridge loan request in the system. This endpoint handles the workflow transitions between different approval states.

### Endpoint
`POST /api/updateApprovalStatus` (actual route may vary depending on your route configuration)

### Input Parameters

#### Required Parameters:
- `id`: Numeric value, must exist in bridge_loans table
- `status`: Character code, must be one of: 'A' (Approved), 'S' (Settled), 'C' (Completed), 'R' (Rejected)
- `action`: Character code, must be one of: 'A' (Approve), 'R' (Reject)

#### Optional Parameters:
- `comment`: Text describing the approval/rejection reason
- `user_id`: ID of the user performing the action

### Example Request
```json
{
    "id": 123,
    "status": "A",
    "action": "A",
    "comment": "Approved by manager",
    "user_id": 456
}
```

### State Transitions
The function handles the following state transitions:
- When `action` = "A" (Approve) and `status` = "A" (Approved) → Next stage = "S" (Settled)
- When `action` = "A" (Approve) and `status` = "S" (Settled) → Next stage = "C" (Completed)
- When `action` = "R" (Reject) → Next stage = "R" (Rejected)

### Database Operations
When successfully executed, the function:
1. Updates the status in the `approval_log` table
2. Creates a new entry in `approval_log` if necessary
3. Updates the status in the `bridge_loans` table
4. Updates the status in the `bridge_loan_items` table

All operations are performed within a database transaction to ensure data integrity.

### Response Format
All responses follow this JSON structure:
```json
{
    "status": "[success|error]",
    "message": "Descriptive message",
    "data": null,
    "meta": null,
    "errors": null
}
```

### Output Possibilities

#### Success Response (HTTP 200)
```json
{
    "status": "success",
    "message": "Approval status updated successfully",
    "data": null,
    "meta": null,
    "errors": null
}
```

#### Validation Error Response (HTTP 422)
Returned when validation fails for the input parameters.
```json
{
    "status": "error",
    "message": "Validation error",
    "data": null,
    "meta": null,
    "errors": {
        "id": [
            "The id field is required."
        ],
        "status": [
            "The status must be one of: A, S, C, R."
        ],
        "action": [
            "The action must be one of: A, R."
        ]
    }
}
```

#### Server Error Response (HTTP 500)
Returned when an unexpected error occurs during processing.
```json
{
    "status": "error",
    "message": "Failed to update approval status",
    "data": null,
    "meta": null,
    "errors": "Exception message details"
}
```

### Status Code Definitions
- **A**: Approved - The loan has been approved but not yet settled
- **S**: Settled - The loan has been settled but the process is not complete
- **C**: Completed - The loan process has been completed
- **R**: Rejected - The loan has been rejected

### Action Code Definitions
- **A**: Approve - Approve the current stage and move to the next stage
- **R**: Reject - Reject the loan regardless of current stage