API Reference — Renglones Presupuestarios y Centros de Costo

Cambio importante (mayo 2026): Los endpoints /cost-centers originales operaban sobre lo que ahora son renglones presupuestarios. Tras el Sub-proyecto 1:

• Renglones presupuestarios → /api/budget/positions (los /cost-centers legacy responden 308 + header Deprecation).
• Centros de costo verdaderos (unidades organizacionales) → /api/accounting/cost-centers.
• Áreas funcionales PDVSA → /api/accounting/functional-areas.

Referencia de endpoints relacionados con las dimensiones contables del módulo de Presupuesto y Contabilidad.

Base URL: http://{host}/api

---

Autenticación

Todos los endpoints requieren un token JWT en el header:

Authorization: Bearer {token}

---

Renglones Presupuestarios (/budget/positions)

Listar renglones

GET /budget/positions

Query params:

Parámetro	Tipo	Descripción
costType	string	OPEX o CAPEX
functionalAreaId	UUID	Filtrar por área funcional
parentId	UUID	Filtrar por renglón padre
status	string	ACTIVE (default) / INACTIVE

Respuesta 200:

[
  {
    "id": "8f2c-...",
    "code": "ACE-1-1AL-LEV",
    "name": "Levantamiento - Alimentación",
    "description": "Servicios de alimentación durante levantamiento",
    "costType": "OPEX",
    "category": "Logística",
    "subCategory": "Alimentación",
    "functionalAreaId": "f1-...",
    "parentId": null,
    "status": "ACTIVE"
  }
]

Permiso requerido: budget:positions:read

CRUD adicional

GET    /budget/positions/:id
POST   /budget/positions
PUT    /budget/positions/:id
DELETE /budget/positions/:id            # desactiva si tiene historial
GET    /budget/positions/by-cost-type/:type
GET    /budget/positions/by-functional-area/:faId

Permiso: budget:positions:write para escritura, :read para lectura.

---

Áreas Funcionales (/accounting/functional-areas)

GET    /accounting/functional-areas
GET    /accounting/functional-areas/:id
POST   /accounting/functional-areas
PUT    /accounting/functional-areas/:id
DELETE /accounting/functional-areas/:id
GET    /accounting/functional-areas/by-category/:category

Permiso: accounting:functional-areas:read|write. Ver Áreas Funcionales.

Respuesta 200 (ejemplo de listar):

[
  {
    "id": "f1-...",
    "code": "LEV",
    "name": "Levantamiento",
    "description": "Levantamiento artificial de hidrocarburos",
    "category": "UPSTREAM_OPERATIONS",
    "status": "ACTIVE"
  }
]

---

Centros de Costo Reales (/accounting/cost-centers)

Modelo nuevo del Sub-proyecto 1: 22 unidades organizacionales con responsable y departamento.

GET    /accounting/cost-centers
GET    /accounting/cost-centers/:id
POST   /accounting/cost-centers
PUT    /accounting/cost-centers/:id
DELETE /accounting/cost-centers/:id
GET    /accounting/cost-centers/:id/tree
GET    /accounting/cost-centers/by-department/:departmentId

Permiso: accounting:cost-centers:read|write.

Respuesta 200 (ejemplo de listar):

[
  {
    "id": "cc-...",
    "code": "CC-OPS-POZOS",
    "name": "Operaciones Pozos",
    "type": "PRODUCTIVE",
    "parentId": "cc-ops-...",
    "level": 2,
    "departmentId": "dept-ops-...",
    "managerId": "emp-...",
    "status": "ACTIVE"
  }
]

---

Mapeo Cuenta ↔ Renglón (/accounting/account-position-links)

Reemplaza el JSONB cost_centers.accounting_accounts.

GET    /accounting/account-position-links
POST   /accounting/account-position-links
DELETE /accounting/account-position-links/:id

GET    /accounting/accounts/:id/positions   # consulta inversa por cuenta
GET    /accounting/positions/:id/accounts   # consulta inversa por renglón

Permiso: accounting:mappings:read|write.

Body POST:

{
  "accountId": "acc-...",
  "budgetPositionId": "bp-...",
  "role": "DEBIT_DEFAULT"  // o CREDIT_DEFAULT, ALLOWED
}

Reglas:

• Sólo un DEBIT_DEFAULT por cuenta.
• Sólo un CREDIT_DEFAULT por cuenta.
• Múltiples ALLOWED por cuenta.

---

Endpoints Legacy (deprecated)

/cost-centers/* → 308 redirect a /budget/positions/*

Header Deprecation: true y Sunset: <fecha> en cada respuesta. Se eliminarán tras 1 release.

---

Dashboard — Ejecución por Renglón

GET /budget/dashboard/execution-by-position

Query params:

Parámetro	Tipo	Default	Descripción
fiscalYear	integer	Año actual	Año fiscal
period	string	—	Período mensual (2026-05)
costType	string	all	opex, capex, all
functionalAreaId	UUID	—	Filtrar por área funcional

Respuesta 200:

{
  "fiscalYear": 2026,
  "costType": "opex",
  "positions": [
    {
      "budgetPositionId": "bp-...",
      "code": "ACE-1-1AL-LEV",
      "name": "Levantamiento - Alimentación",
      "functionalAreaCode": "LEV",
      "costType": "OPEX",
      "totalPlanned": 150000,
      "totalCommitted": 45000,
      "totalExecuted": 80000,
      "totalAvailable": 25000,
      "executionPercentage": "53.33"
    }
  ]
}

Permiso requerido: budget:positions:read

---

Dashboard — Distribución por Área Funcional

GET /budget/dashboard/by-functional-area

Agrupa la ejecución presupuestaria por código de área funcional (PDVSA).

Query params:

Parámetro	Tipo	Default	Descripción
fiscalYear	integer	Año actual	Año fiscal
period	string	—	Período
costType	string	all	opex, capex, all

Respuesta 200:

{
  "fiscalYear": 2026,
  "costType": "all",
  "functionalAreas": [
    {
      "functionalAreaCode": "LEV",
      "functionalAreaName": "Levantamiento",
      "category": "UPSTREAM_OPERATIONS",
      "totalPlanned": 300000,
      "totalCommitted": 90000,
      "totalExecuted": 160000,
      "totalAvailable": 50000,
      "positionCount": 4
    }
  ]
}

Permiso requerido: budget:positions:read

---

Dashboard Tiempo Real (con filtro por dimensión)

GET /budget/dashboard/real-time

Query params:

Parámetro	Tipo	Descripción
fiscalYear	integer	Año fiscal
period	string	Período mensual
budgetType	string	OPEX, CAPEX, ALL
costCenterId	UUID	Filtrar por CC real
budgetPositionId	UUID	Filtrar por renglón
functionalAreaId	UUID	Filtrar por área funcional
projectId	UUID	Filtrar por proyecto

Permiso requerido: budget:read

---

Resumen Ejecutivo (con desglose OPEX/CAPEX)

GET /budget/dashboard/executive-summary

{
  "totalPlanned": 5000000,
  "totalExecuted": 2300000,
  "opex": { "planned": 2000000, "executed": 1200000, "executionPercentage": 60 },
  "capex": { "planned": 3000000, "executed": 1100000, "executionPercentage": 36.67 },
  "byCostType": [
    { "type": "OPEX", "planned": 2000000, "executed": 1200000, "percentage": 60 },
    { "type": "CAPEX", "planned": 3000000, "executed": 1100000, "percentage": 36.67 }
  ]
}

Permiso requerido: budget:read

---

Tendencia Mensual (con filtros por dimensión)

GET /budget/dashboard/monthly-trend

Query params:

Parámetro	Tipo	Descripción
fiscalYear	integer	Año fiscal
costType	string	opex o capex
functionalAreaId	UUID	Filtrar por área funcional
costCenterId	UUID	Filtrar por CC real

Permiso requerido: budget:read

---

Compromisos por Renglón / CC

GET /budget/commitments/summary/by-position
GET /budget/commitments/summary/by-cost-center
GET /budget/commitments/summary/by-functional-area
GET /budget/commitments/summary/by-category

Cada endpoint agrupa los compromisos por la dimensión correspondiente. Estructura típica:

[
  {
    "id": "...",
    "code": "...",
    "name": "...",
    "totalCommitted": 120000,
    "totalInvoiced": 90000,
    "totalPaid": 80000,
    "totalRemaining": 40000,
    "count": 5
  }
]

Permiso requerido: budget:read

---

Códigos de Error

Código HTTP	Descripción
400	Parámetros inválidos o faltantes
401	Token no provisto o inválido
403	Sin permisos para el recurso solicitado
404	Recurso no encontrado
409	Conflicto (UNIQUE, mapeo duplicado, etc.)
422	Validación dimensional fallida (ej. EXPENSE sin cost_center)
500	Error interno

Ejemplo de error 422 (validación dimensional):

{
  "error": "ValidationError",
  "message": "cost_center_id requerido para cuenta EXPENSE"
}

---

Historial de Cambios

Sub-proyecto	Cambio
ERP-23	Creación del módulo CostCenter con CRUD básico
ERP-24	JOIN de BudgetExecution con CostCenter en OPEX dashboard
ERP-30	Filtros OPEX/CAPEX en dashboard, agrupación por código PDVSA
Sub-proyecto 1 (mayo 2026)	Renombre cost_centers→budget_positions; nueva tabla cost_centers (organizacional); tabla functional_areas (26 PDVSA); tabla join account_budget_position_links; 5 dimensiones por línea de asiento

---

Referencias

• Áreas Funcionales
• Renglones Presupuestarios
• Centros de Costo
• Dimensiones Contables
• nomenclatura-pdvsa.md
• flujo-centros-de-costo.md
• guia-administrador.md