Manage Budget Items - Tanqueo Backend API

Overview

Budget items represent individual line items within a budget. Each item has:

Type and Concept: Classification of the expense (e.g., Maintenance → Oil Change)
Frequency: How many times per month the expense occurs
Applicable Months: Array of months (1-12) when this expense applies
Unit Price: Cost per occurrence
Total Value: Automatically calculated as valor_unitario × frecuencia_mes × meses_aplicables.length

Add Item to Budget

Add a new line item to an existing budget.

Endpoint

POST /api/presupuestos/:id/items

Authentication

Requires valid JWT Bearer token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Path Parameters

number

required

Budget ID to add the item to

Request Body

tipo_presupuesto_id

number

required

Budget type ID (e.g., 3 for “Mantenimiento Preventivo”)

concepto_presupuesto_id

number

required

Concept ID within the type (e.g., 15 for “Cambio de Aceite”)

frecuencia_mes

number

required

How many times per month this expense occurs. Example: 1 for monthly, 2 for twice per month.

meses_aplicables

array

required

Array of month numbers (1-12) where this item applies.Examples:

All year: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
Quarterly: [3, 6, 9, 12]
First semester: [1, 2, 3, 4, 5, 6]

valor_unitario

number

required

Unit price for this expense in Colombian pesos (COP).The total value is automatically calculated as: valor_unitario × frecuencia_mes × meses_aplicables.length

Response

number

Created item ID

presupuesto_id

number

Parent budget ID

tipo_presupuesto_id

number

Budget type ID

concepto_presupuesto_id

number

Concept ID

frecuencia_mes

number

Frequency per month

meses_aplicables

array

Array of applicable months

valor_unitario

number

Unit price

valor_total

number

Total value (calculated)

Example Request

curl -X POST "https://api.example.com/api/presupuestos/1/items" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_presupuesto_id": 3,
    "concepto_presupuesto_id": 15,
    "frecuencia_mes": 1,
    "meses_aplicables": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
    "valor_unitario": 250000
  }'

Calculation Example

valor_unitario: 250,000 COP (Oil change cost)
frecuencia_mes: 1 (Once per month)
meses_aplicables: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] (12 months)

valor_total = 250,000 × 1 × 12 = 3,000,000 COP

Example Response

{
  "id": 1,
  "presupuesto_id": 1,
  "tipo_presupuesto_id": 3,
  "concepto_presupuesto_id": 15,
  "frecuencia_mes": 1,
  "meses_aplicables": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "valor_unitario": 250000,
  "valor_total": 3000000
}

Update Budget Item

Update an existing budget item. The total value is automatically recalculated when updating any of the component values.

Endpoint

PUT /api/presupuestos/items/:itemId

Authentication

Requires valid JWT Bearer token.

Path Parameters

itemId

number

required

Budget item ID to update

Request Body

All fields are optional. Only include fields you want to update.

tipo_presupuesto_id

number

Budget type ID

concepto_presupuesto_id

number

Concept ID

frecuencia_mes

number

Frequency per month

meses_aplicables

array

Array of applicable months (1-12)

valor_unitario

number

Unit price

Response

Returns the updated item with recalculated valor_total.

number

Item ID

presupuesto_id

number

Parent budget ID

tipo_presupuesto_id

number

Budget type ID

concepto_presupuesto_id

number

Concept ID

frecuencia_mes

number

Frequency per month

meses_aplicables

array

Array of applicable months

valor_unitario

number

Unit price

valor_total

number

Total value (recalculated)

Example Request

curl -X PUT "https://api.example.com/api/presupuestos/items/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "valor_unitario": 280000,
    "meses_aplicables": [1, 3, 5, 7, 9, 11]
  }'

Calculation Example

Original:
  valor_unitario: 250,000
  frecuencia_mes: 1
  meses_aplicables: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
  valor_total: 3,000,000

Updated:
  valor_unitario: 280,000
  frecuencia_mes: 1 (unchanged)
  meses_aplicables: [1, 3, 5, 7, 9, 11] (6 months)
  valor_total: 280,000 × 1 × 6 = 1,680,000

Example Response

{
  "id": 1,
  "presupuesto_id": 1,
  "tipo_presupuesto_id": 3,
  "concepto_presupuesto_id": 15,
  "frecuencia_mes": 1,
  "meses_aplicables": [1, 3, 5, 7, 9, 11],
  "valor_unitario": 280000,
  "valor_total": 1680000
}

The system automatically fetches current values for fields not included in the update to ensure accurate total calculation.

Delete Budget Item

Delete a budget item from a budget.

Endpoint

DELETE /api/presupuestos/items/:itemId

Authentication

Requires valid JWT Bearer token.

Path Parameters

itemId

number

required

Budget item ID to delete

Response

Returns HTTP 204 No Content on success.

Example Request

curl -X DELETE "https://api.example.com/api/presupuestos/items/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This will permanently delete the budget item. This action cannot be undone.

Common Use Cases

Monthly Preventive Maintenance

{
  "tipo_presupuesto_id": 3,
  "concepto_presupuesto_id": 15,
  "frecuencia_mes": 1,
  "meses_aplicables": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "valor_unitario": 250000
}

Occurs once every month
Applied all 12 months
Total: 250,000 × 1 × 12 = 3,000,000 COP

Quarterly Tire Inspection

{
  "tipo_presupuesto_id": 3,
  "concepto_presupuesto_id": 16,
  "frecuencia_mes": 1,
  "meses_aplicables": [3, 6, 9, 12],
  "valor_unitario": 180000
}

Occurs once per month
Applied in 4 months (quarterly)
Total: 180,000 × 1 × 4 = 720,000 COP

Weekly Washing (First Semester)

{
  "tipo_presupuesto_id": 4,
  "concepto_presupuesto_id": 20,
  "frecuencia_mes": 4,
  "meses_aplicables": [1, 2, 3, 4, 5, 6],
  "valor_unitario": 35000
}

Occurs 4 times per month (weekly)
Applied in 6 months (first semester)
Total: 35,000 × 4 × 6 = 840,000 COP

Biweekly Fuel Budget

{
  "tipo_presupuesto_id": 2,
  "concepto_presupuesto_id": 8,
  "frecuencia_mes": 2,
  "meses_aplicables": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "valor_unitario": 450000
}

Occurs twice per month (biweekly)
Applied all 12 months
Total: 450,000 × 2 × 12 = 10,800,000 COP

Budget Item Workflow

Create Budget: First create the budget header with POST /api/presupuestos
Add Items: Add line items one by one with POST /api/presupuestos/:id/items
Review: Get full budget with items using GET /api/presupuestos/:id
Adjust: Update items as needed with PUT /api/presupuestos/items/:itemId
Approve: Change budget estado to “APROBADO” with PUT /api/presupuestos/:id

Error Responses

400 Bad Request

{
  "error": "Invalid meses_aplicables: must be array of numbers 1-12"
}

401 Unauthorized

{
  "error": "Invalid or expired token"
}

404 Not Found

{
  "error": "Budget item not found"
}

500 Internal Server Error

{
  "error": "Error en el servidor"
}

Authentication

Fuel Tracking

Lubrication Services

Fleet Management

Vehicle Documents

Maintenance

Budgets

Fuel Station Balances

Catalogs

File Upload

​Overview

​Add Item to Budget

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Calculation Example

​Example Response

​Update Budget Item

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Calculation Example

​Example Response

​Delete Budget Item

​Endpoint

​Authentication

​Path Parameters

​Response

​Example Request

​Common Use Cases

​Monthly Preventive Maintenance

​Quarterly Tire Inspection

​Weekly Washing (First Semester)

​Biweekly Fuel Budget

​Budget Item Workflow

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

Build docs developers (and LLMs) love

Overview

Add Item to Budget

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Request

Calculation Example

Example Response

Update Budget Item

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Request

Calculation Example

Example Response

Delete Budget Item

Endpoint

Authentication

Path Parameters

Response

Example Request

Common Use Cases

Monthly Preventive Maintenance

Quarterly Tire Inspection

Weekly Washing (First Semester)

Biweekly Fuel Budget

Budget Item Workflow

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error