Expense Calculation Service
API Contract
REST
/api/v1/expense-calculations
6 endpoints
GET
/api/v1/expense-calculations/api/v1/expense-calculations
List historical expense calculations
Public
Response Example
{
"data": [
{
"id": "calc-001",
"expense_id": "exp-8821",
"selected_types": [
"kilometers",
"tolls"
],
"total_amount": 47.5,
"currency": "EUR",
"breakdown": [
{
"expense_type": "kilometers",
"amount": 37.5,
"unit": "km",
"quantity": 75
},
{
"expense_type": "tolls",
"amount": 10,
"unit": "fixed",
"quantity": 1
}
],
"calculated_at": "2026-03-26T09:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1
}
}
GET
/api/v1/expense-calculations/api/v1/expense-calculations/:id
Get a specific calculation result
Public
Response Example
{
"id": "calc-001",
"expense_id": "exp-8821",
"selected_types": [
"kilometers",
"tolls"
],
"total_amount": 47.5,
"currency": "EUR",
"breakdown": [
{
"expense_type": "kilometers",
"amount": 37.5,
"unit": "km",
"quantity": 75
},
{
"expense_type": "tolls",
"amount": 10,
"unit": "fixed",
"quantity": 1
}
],
"formula_descriptions": {
"kilometers": "Rate: €0.50/km × declared distance",
"tolls": "Reimbursed at cost with receipt"
},
"calculated_at": "2026-03-26T09:30:00Z"
}
POST
/api/v1/expense-calculations/api/v1/expense-calculations
Calculate reimbursement for selected expense types and input params
Public
Request Example
{
"expense_id": "exp-8824",
"selected_types": [
"kilometers",
"parking"
],
"inputs": {
"kilometers": {
"distance_km": 120,
"vehicle_type": "personal_car"
},
"parking": {
"duration_hours": 3,
"cost_per_hour": 2.5
}
}
}Response Example
{
"id": "calc-002",
"expense_id": "exp-8824",
"selected_types": [
"kilometers",
"parking"
],
"total_amount": 67.5,
"currency": "EUR",
"breakdown": [
{
"expense_type": "kilometers",
"amount": 60,
"unit": "km",
"quantity": 120
},
{
"expense_type": "parking",
"amount": 7.5,
"unit": "hours",
"quantity": 3
}
],
"formula_descriptions": {
"kilometers": "Rate: €0.50/km × 120 km",
"parking": "€2.50/hr × 3 hrs"
},
"calculated_at": "2026-03-26T11:45:00Z"
}
PUT
/api/v1/expense-calculations/api/v1/expense-calculations/:id
Recalculate with updated input parameters
Public
Request Example
{
"selected_types": [
"kilometers",
"parking"
],
"inputs": {
"kilometers": {
"distance_km": 140,
"vehicle_type": "personal_car"
},
"parking": {
"duration_hours": 3,
"cost_per_hour": 2.5
}
}
}Response Example
{
"id": "calc-002",
"expense_id": "exp-8824",
"selected_types": [
"kilometers",
"parking"
],
"total_amount": 77.5,
"currency": "EUR",
"breakdown": [
{
"expense_type": "kilometers",
"amount": 70,
"unit": "km",
"quantity": 140
},
{
"expense_type": "parking",
"amount": 7.5,
"unit": "hours",
"quantity": 3
}
],
"formula_descriptions": {
"kilometers": "Rate: €0.50/km × 140 km",
"parking": "€2.50/hr × 3 hrs"
},
"calculated_at": "2026-03-26T11:50:00Z"
}
DELETE
/api/v1/expense-calculations/api/v1/expense-calculations/:id
Delete a calculation record
Public
Response Example
{
"success": true,
"deleted_id": "calc-002"
}
GET
/api/v1/expense-calculations/api/v1/expense-calculations/required-inputs/:expense_type
Get required input fields for a specific expense type
Public
Response Example
{
"expense_type": "kilometers",
"required_inputs": [
{
"field_id": "distance_km",
"label": "Distance (km)",
"type": "number",
"min": 0,
"max": 5000,
"unit": "km",
"required": true
},
{
"field_id": "vehicle_type",
"label": "Vehicle Type",
"type": "enum",
"options": [
"personal_car",
"motorcycle",
"electric_vehicle"
],
"required": true
}
]
}