Admin Endpoints

Propósito

Los endpoints de administración (/api/admin/*) proporcionan funcionalidad CRUD para configuración empresarial y maestros del sistema. Todos requieren autenticación JWT y algunos requieren rol de administrador.

Seguridad: Todos los endpoints requieren authenticateToken. Los marcados con (ADMIN) requieren rol ADMIN o SUPER_ADMIN.

Gestión de capital empresarial (aportes, aumentos, reducciones de capital).

GET /api/admin/capital

Lista entradas de capital con filtros opcionales.

Query Parameters:

estado (opcional): Estado de la entrada (ej: PENDIENTE, APROBADO)
tipo_capital (opcional): Tipo de capital
fecha_desde (opcional): Filtro fecha inicio (YYYY-MM-DD)
fecha_hasta (opcional): Filtro fecha fin (YYYY-MM-DD)
limit (opcional): Número máximo de resultados
offset (opcional): Offset para paginación

Headers:

Cookie: sid=<jwt_token>

Respuesta exitosa (200):

[
  {
    "id": "uuid-capital-1",
    "tipo_capital": "APORTE_INICIAL",
    "monto": 50000000,
    "moneda": "CLP",
    "fecha": "2025-01-15",
    "estado": "APROBADO"
  }
]

Errores:

401 Unauthorized → Sin token o token inválido
500 Internal Server Error → Error del servidor

Ver código: capital.ts

GET /api/admin/capital/:id

Obtiene entrada de capital por ID.

Path Parameters:

id (required): UUID de la entrada

Respuesta exitosa (200):

{
  "id": "uuid-capital-1",
  "tipo_capital": "AUMENTO",
  "monto": 10000000,
  "moneda": "CLP",
  "fecha": "2026-01-10",
  "estado": "PENDIENTE",
  "descripcion": "Aumento de capital por nuevos socios"
}

Errores:

401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

POST /api/admin/capital

Crea nueva entrada de capital.

Body:

{
  "tipo_capital": "AUMENTO",
  "monto": 20000000,
  "moneda": "CLP",
  "fecha": "2026-01-18",
  "descripcion": "Aumento de capital 2026"
}

Respuesta exitosa (201):

{
  "id": "uuid-new-capital",
  "tipo_capital": "AUMENTO",
  "monto": 20000000,
  "moneda": "CLP",
  "fecha": "2026-01-18",
  "estado": "PENDIENTE"
}

Errores:

400 Bad Request → Datos inválidos
401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

PUT /api/admin/capital/:id

Actualiza entrada de capital existente.

Path Parameters:

id (required): UUID de la entrada

Body (campos opcionales):

{
  "monto": 25000000,
  "descripcion": "Monto actualizado"
}

Respuesta exitosa (200):

{
  "id": "uuid-capital-1",
  "monto": 25000000,
  "descripcion": "Monto actualizado"
}

Errores:

400 Bad Request → Datos inválidos
401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

DELETE /api/admin/capital/:id

Elimina entrada de capital.

Path Parameters:

id (required): UUID de la entrada

Respuesta exitosa (204): Sin contenido.

Errores:

401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

POST /api/admin/capital/:id/approve (ADMIN)

Aprueba entrada de capital. Requiere rol ADMIN o SUPER_ADMIN.

Path Parameters:

id (required): UUID de la entrada

Respuesta exitosa (200):

{
  "id": "uuid-capital-1",
  "estado": "APROBADO",
  "aprobado_por": "user-id",
  "fecha_aprobacion": "2026-01-18T15:30:00Z"
}

Errores:

400 Bad Request → Ya aprobado o inválido
401 Unauthorized → Sin autenticación
403 Forbidden → Sin permisos de admin
500 Internal Server Error → Error del servidor

Plan Contable (Chart of Accounts)

Gestión del plan de cuentas contable.

GET /api/admin/chart-of-accounts

Lista todas las cuentas del plan contable.

Respuesta exitosa (200):

[
  {
    "codigo": "1",
    "nombre": "ACTIVO",
    "nivel": 1,
    "tipo": "GRUPO"
  },
  {
    "codigo": "1.1",
    "nombre": "ACTIVO CIRCULANTE",
    "nivel": 2,
    "tipo": "GRUPO",
    "padre": "1"
  },
  {
    "codigo": "1.1.01",
    "nombre": "Caja",
    "nivel": 3,
    "tipo": "CUENTA",
    "padre": "1.1"
  }
]

Errores:

401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

Ver código: chart-of-accounts.ts

GET /api/admin/chart-of-accounts/tree

Lista cuentas como estructura de árbol (alias de /).

Respuesta: Idéntica a GET /api/admin/chart-of-accounts

GET /api/admin/chart-of-accounts/:codigo

Obtiene cuenta por código.

Path Parameters:

codigo (required): Código de cuenta (ej: 1.1.01)

Respuesta exitosa (200):

{
  "codigo": "1.1.01",
  "nombre": "Caja",
  "nivel": 3,
  "tipo": "CUENTA",
  "padre": "1.1",
  "descripcion": "Efectivo en caja"
}

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Cuenta no existe
500 Internal Server Error → Error del servidor

POST /api/admin/chart-of-accounts

Crea nueva cuenta en el plan contable.

Body:

{
  "codigo": "1.1.02",
  "nombre": "Banco",
  "tipo": "CUENTA",
  "padre": "1.1",
  "descripcion": "Cuenta corriente bancaria"
}

Respuesta exitosa (201):

{
  "codigo": "1.1.02",
  "nombre": "Banco",
  "nivel": 3,
  "tipo": "CUENTA",
  "padre": "1.1"
}

Errores:

400 Bad Request → Código duplicado o datos inválidos
401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

PUT /api/admin/chart-of-accounts/:codigo

Actualiza cuenta existente.

Path Parameters:

codigo (required): Código de cuenta

Body (campos opcionales):

{
  "nombre": "Banco Chile",
  "descripcion": "Cuenta corriente Banco de Chile"
}

Respuesta exitosa (200):

{
  "codigo": "1.1.02",
  "nombre": "Banco Chile",
  "descripcion": "Cuenta corriente Banco de Chile"
}

Errores:

400 Bad Request → Datos inválidos
401 Unauthorized → Sin autenticación
404 Not Found → Cuenta no existe
500 Internal Server Error → Error del servidor

DELETE /api/admin/chart-of-accounts/:codigo

Elimina cuenta del plan contable.

Path Parameters:

codigo (required): Código de cuenta

Respuesta exitosa (204): Sin contenido.

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Cuenta no existe
500 Internal Server Error → Error del servidor

Empresa (Company Configuration)

Configuración de la empresa actual del tenant.

GET /api/admin/company

Obtiene configuración de la empresa.

Respuesta exitosa (200):

{
  "rut": "76123456-7",
  "razon_social": "Mi Empresa SPA",
  "giro": "Servicios de consultoría",
  "direccion": "Av. Principal 123",
  "comuna": "Santiago",
  "region": "Metropolitana",
  "telefono": "+56912345678",
  "email": "[email protected]"
}

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Empresa no configurada
500 Internal Server Error → Error del servidor

Ver código: company.ts

PUT /api/admin/company

Actualiza configuración de empresa.

Body (todos los campos opcionales):

{
  "razon_social": "Mi Empresa Actualizada SPA",
  "direccion": "Nueva Direccion 456",
  "telefono": "+56987654321"
}

Respuesta exitosa (200):

{
  "rut": "76123456-7",
  "razon_social": "Mi Empresa Actualizada SPA",
  "direccion": "Nueva Direccion 456",
  "telefono": "+56987654321"
}

Errores:

400 Bad Request → Datos inválidos o sin campos a actualizar
401 Unauthorized → Sin autenticación
404 Not Found → Empresa no existe
500 Internal Server Error → Error del servidor

Representantes Legales

Gestión de representantes legales de la empresa.

GET /api/admin/representatives

Lista representantes legales.

Query Parameters:

activeOnly (opcional): true para solo activos, false para todos

Respuesta exitosa (200):

[
  {
    "id": "uuid-rep-1",
    "rut": "12345678-9",
    "nombre": "Juan",
    "apellido_paterno": "Pérez",
    "apellido_materno": "González",
    "cargo": "Gerente General",
    "activo": true,
    "fecha_nombramiento": "2024-01-01"
  }
]

Errores:

401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

Ver código: representatives.ts

GET /api/admin/representatives/:id

Obtiene representante por ID.

Path Parameters:

id (required): UUID del representante

Respuesta exitosa (200):

{
  "id": "uuid-rep-1",
  "rut": "12345678-9",
  "nombre": "Juan",
  "apellido_paterno": "Pérez",
  "apellido_materno": "González",
  "cargo": "Gerente General",
  "activo": true,
  "email": "[email protected]",
  "telefono": "+56912345678"
}

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Representante no existe
500 Internal Server Error → Error del servidor

POST /api/admin/representatives

Crea nuevo representante legal.

Body:

{
  "rut": "23456789-0",
  "nombre": "María",
  "apellido_paterno": "López",
  "apellido_materno": "Silva",
  "cargo": "Directora",
  "email": "[email protected]",
  "telefono": "+56987654321"
}

Respuesta exitosa (201):

{
  "id": "uuid-new-rep",
  "rut": "23456789-0",
  "nombre": "María",
  "apellido_paterno": "López",
  "apellido_materno": "Silva",
  "cargo": "Directora",
  "activo": false
}

Errores:

400 Bad Request → RUT inválido o datos faltantes
401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

PUT /api/admin/representatives/:id

Actualiza representante existente.

Path Parameters:

id (required): UUID del representante

Body (campos opcionales):

{
  "cargo": "Gerente General y Director",
  "email": "[email protected]"
}

Respuesta exitosa (200):

{
  "id": "uuid-rep-1",
  "cargo": "Gerente General y Director",
  "email": "[email protected]"
}

Errores:

400 Bad Request → Datos inválidos o sin campos
401 Unauthorized → Sin autenticación
404 Not Found → Representante no existe
500 Internal Server Error → Error del servidor

DELETE /api/admin/representatives/:id

Elimina representante legal.

Path Parameters:

id (required): UUID del representante

Respuesta exitosa (204): Sin contenido.

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Representante no existe
500 Internal Server Error → Error del servidor

POST /api/admin/representatives/:id/set-active (ADMIN)

Marca representante como activo. Requiere rol ADMIN o SUPER_ADMIN.

Path Parameters:

id (required): UUID del representante

Respuesta exitosa (200):

{
  "id": "uuid-rep-1",
  "activo": true,
  "fecha_activacion": "2026-01-18T15:45:00Z"
}

Errores:

401 Unauthorized → Sin autenticación
403 Forbidden → Sin permisos de admin
404 Not Found → Representante no existe
500 Internal Server Error → Error del servidor

Configuración del Sistema

Parámetros de configuración del sistema.

GET /api/admin/system-config

Obtiene todas las configuraciones del sistema.

Respuesta exitosa (200):

[
  {
    "clave": "tax_year",
    "valor": "2026",
    "descripcion": "Año tributario actual"
  },
  {
    "clave": "enable_notifications",
    "valor": "true",
    "descripcion": "Habilitar notificaciones por email"
  }
]

Errores:

401 Unauthorized → Sin autenticación
500 Internal Server Error → Error del servidor

Ver código: system-config.ts

GET /api/admin/system-config/:clave

Obtiene configuración por clave.

Path Parameters:

clave (required): Clave de configuración

Respuesta exitosa (200):

{
  "clave": "tax_year",
  "valor": "2026",
  "descripcion": "Año tributario actual",
  "tipo": "number"
}

Errores:

401 Unauthorized → Sin autenticación
404 Not Found → Clave no existe
500 Internal Server Error → Error del servidor

PUT /api/admin/system-config/:clave

Actualiza configuración por clave.

Path Parameters:

clave (required): Clave de configuración

Body:

{
  "valor": "2027"
}

Respuesta exitosa (200):

{
  "clave": "tax_year",
  "valor": "2027",
  "actualizado_en": "2026-01-18T15:50:00Z"
}

Errores:

400 Bad Request → Valor inválido o sin campos
401 Unauthorized → Sin autenticación
404 Not Found → Clave no existe
500 Internal Server Error → Error del servidor

Notas de Implementación

Autenticación: Todos los endpoints usan middleware authenticateToken que valida JWT desde cookie sid.

Roles: Endpoints marcados con (ADMIN) usan middleware requireRole(['ADMIN', 'SUPER_ADMIN']).

Service Context: Todos los endpoints construyen ServiceContext con:

tenantDb: Nombre de base de datos del tenant
userId: ID del usuario autenticado
requestId: Header x-request-id para tracing

Error Handling: Todos los endpoints retornan errores en formato:

{
  "error": "Mensaje de error descriptivo"
}

Referencias

Command Endpoints - Endpoints de comando y configuración
Common Endpoints - Endpoints de datos comunes
Remuneraciones Endpoints - Endpoints de nómina

Servicios relacionados:

Admin Endpoints

Propósito

Capital Social

GET /api/admin/capital

GET /api/admin/capital/:id

POST /api/admin/capital

PUT /api/admin/capital/:id

DELETE /api/admin/capital/:id

POST /api/admin/capital/:id/approve (ADMIN)

Plan Contable (Chart of Accounts)

GET /api/admin/chart-of-accounts

GET /api/admin/chart-of-accounts/tree

GET /api/admin/chart-of-accounts/:codigo

POST /api/admin/chart-of-accounts

PUT /api/admin/chart-of-accounts/:codigo

DELETE /api/admin/chart-of-accounts/:codigo

Empresa (Company Configuration)

GET /api/admin/company

PUT /api/admin/company

Representantes Legales

GET /api/admin/representatives

GET /api/admin/representatives/:id

POST /api/admin/representatives

PUT /api/admin/representatives/:id

DELETE /api/admin/representatives/:id

POST /api/admin/representatives/:id/set-active (ADMIN)

Configuración del Sistema

GET /api/admin/system-config

GET /api/admin/system-config/:clave

PUT /api/admin/system-config/:clave

Notas de Implementación

Referencias