Create & Update Budgets - Tanqueo Backend API

Create Budget

Create a new budget with optional line items. The budget will be created in BORRADOR (draft) status by default.

Endpoint

POST /api/presupuestos

Authentication

Requires valid JWT Bearer token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body

empresa_id

number

required

Company ID

area_operacion_id

number

required

Operational area/department ID

grupo_rubro_id

number

required

Category group ID (top-level category)

rubro_id

number

required

Subcategory ID (must belong to grupo_rubro_id)

anio

number

required

Fiscal year (e.g., 2024)

vehiculo_id

number | null

Vehicle ID. Optional - leave null for department-wide budgets not tied to a specific vehicle.

estado

string

default:"BORRADOR"

Budget status: “BORRADOR” (draft) or “APROBADO” (approved)

empleado_id

number | null

Employee ID responsible for this budget. Optional.

items

array

Array of budget line items to create with the budget. Optional - can be added later.

tipo_presupuesto_id

number

required

Budget type ID (e.g., maintenance, fuel)

concepto_presupuesto_id

number

required

Concept ID (must belong to tipo_presupuesto_id)

frecuencia_mes

number

required

How many times per month this expense occurs

meses_aplicables

array

required

Array of month numbers (1-12) where this item applies. Example: [1, 3, 6, 9, 12]

valor_unitario

number

required

Unit price for this expense. valor_total is calculated automatically as: valor_unitario × frecuencia_mes × meses_aplicables.length

Response

number

Created budget ID

empresa_id

number

Company ID

vehiculo_id

number | null

Vehicle ID

area_operacion_id

number

Operational area ID

grupo_rubro_id

number

Category group ID

rubro_id

number

Subcategory ID

anio

number

Fiscal year

estado

string

Status: “BORRADOR” or “APROBADO”

empleado_id

number | null

Employee ID

created_at

string

Creation timestamp

Example Request

curl -X POST "https://api.example.com/api/presupuestos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": 1,
    "vehiculo_id": 42,
    "area_operacion_id": 5,
    "grupo_rubro_id": 10,
    "rubro_id": 25,
    "anio": 2024,
    "estado": "BORRADOR",
    "empleado_id": 100,
    "items": [
      {
        "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
      },
      {
        "tipo_presupuesto_id": 3,
        "concepto_presupuesto_id": 16,
        "frecuencia_mes": 2,
        "meses_aplicables": [3, 6, 9, 12],
        "valor_unitario": 180000
      }
    ]
  }'

Example Response

{
  "id": 1,
  "empresa_id": 1,
  "vehiculo_id": 42,
  "area_operacion_id": 5,
  "grupo_rubro_id": 10,
  "rubro_id": 25,
  "anio": 2024,
  "estado": "BORRADOR",
  "empleado_id": 100,
  "created_at": "2024-01-15T10:30:00Z"
}

The items are created separately after the budget header. If item creation fails, the budget header is automatically rolled back.

Update Budget

Update an existing budget’s header information. To update items, use the item-specific endpoints.

Endpoint

PUT /api/presupuestos/:id

Authentication

Requires valid JWT Bearer token.

Path Parameters

number

required

Budget ID to update

Request Body

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

empresa_id

number

Company ID

vehiculo_id

number | null

Vehicle ID

area_operacion_id

number

Operational area ID

grupo_rubro_id

number

Category group ID

rubro_id

number

Subcategory ID

anio

number

Fiscal year

estado

string

Budget status: “BORRADOR” or “APROBADO”

empleado_id

number | null

Employee ID

Response

Returns the updated budget object with the same structure as the create response.

Example Request

curl -X PUT "https://api.example.com/api/presupuestos/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "APROBADO",
    "empleado_id": 101
  }'

Example Response

{
  "id": 1,
  "empresa_id": 1,
  "vehiculo_id": 42,
  "area_operacion_id": 5,
  "grupo_rubro_id": 10,
  "rubro_id": 25,
  "anio": 2024,
  "estado": "APROBADO",
  "empleado_id": 101,
  "created_at": "2024-01-15T10:30:00Z"
}

Delete Budget

Delete a budget and all its associated items. This action is irreversible.

Endpoint

DELETEapi/presupuestos/:id

Authentication

Requires valid JWT Bearer token.

Path Parameters

number

required

Budget ID to delete

Response

Returns HTTP 204 No Content on success.

Example Request

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

This will permanently delete the budget and all its items. This action cannot be undone.

Catalog Management

Create budget types and concepts to build your budget structure.

Create Budget Type

Create a new budget type (e.g., “Maintenance”, “Fuel”, “Supplies”).

Requires ADMIN role.

Endpoint

POST /api/presupuestos/tipos

Authentication

Requires valid JWT Bearer token with ADMIN role.

Request Body

nombre

string

required

Type name (e.g., “Mantenimiento Preventivo”)

descripcion

string

Optional description

padre_id

number

required

Parent rubro ID from maestro_rubros

Example Request

curl -X POST "https://api.example.com/api/presupuestos/tipos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Mantenimiento Preventivo",
    "descripcion": "Mantenimientos programados regulares",
    "padre_id": 10
  }'

Example Response

{
  "id": 3,
  "nombre": "Mantenimiento Preventivo",
  "descripcion": "Mantenimientos programados regulares",
  "padre": 10,
  "activo": true
}

Create Budget Concept

Create a new budget concept within a type (e.g., “Oil Change”, “Tire Replacement”).

Requires ADMIN role.

Endpoint

POST /api/presupuestos/conceptos

Authentication

Requires valid JWT Bearer token with ADMIN role.

Request Body

nombre

string

required

Concept name (e.g., “Cambio de Aceite”)

tipo_presupuesto_id

number

required

Budget type ID this concept belongs to

unidad

string

Unit of measurement (e.g., “Servicio”, “Galón”, “Unidad”)

Example Request

curl -X POST "https://api.example.com/api/presupuestos/conceptos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Cambio de Aceite",
    "tipo_presupuesto_id": 3,
    "unidad": "Servicio"
  }'

Example Response

{
  "id": 15,
  "tipo_presupuesto_id": 3,
  "nombre": "Cambio de Aceite",
  "unidad": "Servicio",
  "activo": true
}

Get Catalog Data

Retrieve catalog data for building budget forms.

Get Rubros (Categories)

Get the master list of budget categories and subcategories.

Endpoint

GET /api/presupuestos/rubros

Query Parameters

tipo

string

Filter by type: “DEPENDENCIA”, “GRUPO_RUBRO”, or “RUBRO”

nivel

number

Filter by hierarchy level (1, 2, 3)

padre_id

number

Filter by parent rubro ID

Example Request

# Get all top-level grupos (category groups)
curl -X GET "https://api.example.com/api/presupuestos/rubros?nivel=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get subcategories of a specific group
curl -X GET "https://api.example.com/api/presupuestos/rubros?padre_id=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Budget Types

Get all budget types.

Endpoint

GET /api/presupuestos/tipos

Query Parameters

padre_id

number

Filter by parent rubro ID

Example Request

curl -X GET "https://api.example.com/api/presupuestos/tipos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Budget Concepts

Get all budget concepts, optionally filtered by type.

Endpoint

GET /api/presupuestos/conceptos

Query Parameters

tipo_id

number

Filter by budget type ID

Example Request

# Get all concepts for maintenance type
curl -X GET "https://api.example.com/api/presupuestos/conceptos?tipo_id=3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Responses

400 Bad Request

{
  "error": "Nombre y rubro padre son requeridos"
}

403 Forbidden

{
  "error": "No tiene permisos para realizar esta acción"
}

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

​Create Budget

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Update Budget

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Delete Budget

​Endpoint

​Authentication

​Path Parameters

​Response

​Example Request

​Catalog Management

​Create Budget Type

​Endpoint

​Authentication

​Request Body

​Example Request

​Example Response

​Create Budget Concept

​Endpoint

​Authentication

​Request Body

​Example Request

​Example Response

​Get Catalog Data

​Get Rubros (Categories)

​Endpoint

​Query Parameters

​Example Request

​Get Budget Types

​Endpoint

​Query Parameters

​Example Request

​Get Budget Concepts

​Endpoint

​Query Parameters

​Example Request

​Error Responses

​400 Bad Request

​403 Forbidden

​500 Internal Server Error

Build docs developers (and LLMs) love

Create Budget

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Update Budget

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

Delete Budget

Endpoint

Authentication

Path Parameters

Response

Example Request

Catalog Management

Create Budget Type

Endpoint

Authentication

Request Body

Example Request

Example Response

Create Budget Concept

Endpoint

Authentication

Request Body

Example Request

Example Response

Get Catalog Data

Get Rubros (Categories)

Endpoint

Query Parameters

Example Request

Get Budget Types

Endpoint

Query Parameters

Example Request

Get Budget Concepts

Endpoint

Query Parameters

Example Request

Error Responses

400 Bad Request

403 Forbidden

500 Internal Server Error