Saltar al contenido principal

API Reference — Centros de Costo

Referencia completa de endpoints del módulo de Centros de Costo del ERP del Consorcio Alvorada & Cladoca.

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

Autenticación​

Todos los endpoints requieren un token JWT en el header:

Authorization: Bearer {token}

Centros de Costo (CRUD)​

Listar centros de costo​

GET /cost-centers

Query params:

ParámetroTipoDescripción
costTypestringFiltrar por tipo: OPEX, CAPEX
departmentIdintegerFiltrar por departamento
isActivebooleanSolo activos (default: true)
pdvsaCodestringFiltrar por código PDVSA

Respuesta 200:

[
  {
    "id": 7,
    "code": "CC-LEV-001",
    "name": "Levantamiento Topográfico",
    "pdvsaCode": "LEV",
    "pdvsaDescription": "Levantamiento Topográfico",
    "costType": "OPEX",
    "departmentId": 3,
    "isActive": true
  }
]

Permiso requerido: cost-centers:read

Obtener un centro de costo​

GET /cost-centers/:id

Respuesta 200: objeto CostCenter con asociaciones (departamento, líneas presupuestarias activas).

Permiso requerido: cost-centers:read

Crear centro de costo​

POST /cost-centers

Body:

{
  "code": "CC-001",
  "name": "Nombre del CC",
  "pdvsaCode": "LEV",
  "pdvsaDescription": "Levantamiento Topográfico",
  "costType": "OPEX",
  "departmentId": 3
}

Respuesta 201: objeto CostCenter creado.

Permiso requerido: cost-centers:write

Actualizar centro de costo​

PATCH /cost-centers/:id

Body: campos parciales a actualizar (mismo esquema que POST).

Respuesta 200: objeto actualizado.

Permiso requerido: cost-centers:write

Desactivar centro de costo​

DELETE /cost-centers/:id

Realiza soft delete (sets isActive = false). No elimina registros históricos.

Respuesta 200: { "message": "Centro de costo desactivado" }

Permiso requerido: cost-centers:delete

Dashboard — Ejecución por Centro de Costo​

Ejecución agrupada por CC​

GET /budget/dashboard/execution-by-cost-center

Query params:

ParámetroTipoDefaultDescripción
fiscalYearintegerAño actualAño fiscal a consultar
periodstring—Período (ej. 2026-01)
costTypestringallopex, capex, o all

Respuesta 200:

{
  "fiscalYear": 2026,
  "costType": "opex",
  "costCenters": [
    {
      "costCenterId": 7,
      "costCenterCode": "CC-LEV-001",
      "costCenterName": "Levantamiento Topográfico",
      "pdvsaCode": "LEV",
      "pdvsaDescription": "Levantamiento Topográfico",
      "costType": "OPEX",
      "totalPlanned": 150000,
      "totalCommitted": 45000,
      "totalExecuted": 80000,
      "totalAvailable": 25000,
      "executionPercentage": "53.33"
    }
  ]
}

Permiso requerido: cost-centers:reports

Distribución por código PDVSA​

GET /budget/dashboard/by-pdvsa-code

Agrupa la ejecución presupuestaria por código PDVSA (en lugar de por ID de CC individual).

Query params:

ParámetroTipoDefaultDescripción
fiscalYearintegerAño actualAño fiscal
periodstring—Período
costTypestringallopex, capex, o all

Respuesta 200:

{
  "fiscalYear": 2026,
  "costType": "all",
  "pdvsaGroups": [
    {
      "pdvsaCode": "LEV",
      "pdvsaDescription": "Levantamiento Topográfico",
      "costType": "OPEX",
      "totalPlanned": 300000,
      "totalCommitted": 90000,
      "totalExecuted": 160000,
      "totalAvailable": 50000,
      "costCenterCount": 2
    }
  ]
}

Permiso requerido: cost-centers:reports

Dashboard Tiempo Real (con filtro por CC)​

GET /budget/dashboard/real-time

Query params:

ParámetroTipoDescripción
fiscalYearintegerAño fiscal
periodstringPeríodo mensual
budgetTypestringOPEX, CAPEX, ALL
costCenterIdintegerFiltrar por CC específico

Permiso requerido: budget:read

Resumen Ejecutivo (con desglose OPEX/CAPEX)​

GET /budget/dashboard/executive-summary

La respuesta incluye el campo byCostType:

{
  "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 OPEX/CAPEX/PDVSA)​

GET /budget/dashboard/monthly-trend

Query params:

ParámetroTipoDescripción
fiscalYearintegerAño fiscal
costTypestringopex o capex para filtrar
pdvsaCodestringFiltrar por código PDVSA específico

Permiso requerido: budget:read

Compromisos por Centro de Costo​

Resumen de compromisos por CC​

GET /budget/commitments/summary/by-cost-center

Query params:

ParámetroTipoDescripción
fiscalYearintegerAño fiscal
budgetTypestringOPEX o CAPEX
costTypestringopex, capex, o all

Respuesta 200:

[
  {
    "costCenterId": 7,
    "costCenterCode": "CC-LEV-001",
    "costCenterName": "Levantamiento Topográfico",
    "pdvsaCode": "LEV",
    "pdvsaDescription": "Levantamiento Topográfico",
    "totalCommitted": 120000,
    "totalPaid": 80000,
    "totalRemaining": 40000
  }
]

Permiso requerido: budget:read

Resumen de compromisos por categoría​

GET /budget/commitments/summary/by-category

Query params:

ParámetroTipoDescripción
fiscalYearintegerAño fiscal
budgetTypestringOPEX o CAPEX

Respuesta 200:

[
  {
    "categoryId": 3,
    "categoryName": "Servicios Técnicos",
    "categoryCode": "ST",
    "totalCommitted": 450000,
    "totalInvoiced": 320000,
    "totalPaid": 280000,
    "totalRemaining": 170000,
    "count": 12
  }
]

Permiso requerido: budget:read

Códigos de Error​

Código HTTPDescripción
400Parámetros inválidos o faltantes
401Token no provisto o inválido
403Sin permisos para el recurso solicitado
404Centro de costo no encontrado
500Error interno del servidor

Ejemplo de error 403:​

{
  "error": "Forbidden",
  "message": "No tiene permiso cost-centers:reports"
}

Cambios de ERP-23 a ERP-30​

ERPCambio
ERP-23Creación del módulo CostCenter con CRUD básico
ERP-24JOIN de BudgetExecution con CostCenter en OPEX dashboard
ERP-30getExecutionByCostCenter (costType param), getByPdvsaCode, getCommitmentsSummaryByCostCenter, fix filtro budgetType en RealTime, fix getCommitmentsSummaryByCategory (500 error)

Referencias​