Administración API

Propósito

Los endpoints bajo /api/admin/* proveen configuración empresarial y maestros del sistema: capital social, plan contable, datos de la empresa, representantes legales (que también actúan como socios), parámetros generales del sistema y configuración contable (cuentas y conceptos). Todos requieren autenticación JWT; los marcados con (ADMIN) requieren rol ADMIN o SUPER_ADMIN vía requireRole.

El endpoint interno /api/internal/manual-cuentas (consumido por Jean d’Arc en build) vive en Command Center API.

Mapa de Familias

Familia	Prefijo	Router	Servicio responsable
Capital social	/api/admin/capital	routes/admin/capital.ts	CapitalService
Plan contable (chart of accounts)	/api/admin/chart-of-accounts	routes/admin/chart-of-accounts.ts	ChartOfAccountsService
Empresa	/api/admin/company	routes/admin/company.ts	CompanyService
Representantes legales / socios	/api/admin/representatives	routes/admin/representatives.ts	LegalRepService
Configuración del sistema	/api/admin/system-config	routes/admin/system-config.ts	SystemConfigService
Configuración contable	/api/admin/config-contable	routes/admin/config-contable.ts	ConfigContableService

Capital Social

Aportes, aumentos y reducciones de capital de la empresa. La aprobación de cada entrada está restringida a ADMIN.

Método	Ruta	Uso
GET	/api/admin/capital	Lista entradas con filtros (estado, tipo_capital, fecha_desde, fecha_hasta, limit, offset).
GET	/api/admin/capital/:id	Detalle de una entrada.
POST	/api/admin/capital	Crea entrada de capital (estado inicial PENDIENTE).
PUT	/api/admin/capital/:id	Actualiza monto, descripción u otros campos.
DELETE	/api/admin/capital/:id	Elimina entrada.
POST	/api/admin/capital/:id/approve (ADMIN)	Aprueba la entrada (cambia estado a APROBADO).

Listar capital

curl -X GET "http://localhost:8000/api/admin/capital?estado=PENDIENTE" -b cookies.txt

Response 200

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

Aprobar (ADMIN)

curl -X POST http://localhost:8000/api/admin/capital/uuid-capital-1/approve \
  -b cookies.txt

Plan Contable (Chart of Accounts)

Plan de cuentas instanciado del tenant. La vista jerárquica es la misma en / y en /tree.

Método	Ruta	Uso
GET	/api/admin/chart-of-accounts	Lista cuentas del plan.
GET	/api/admin/chart-of-accounts/tree	Alias jerárquico de /.
GET	/api/admin/chart-of-accounts/:codigo	Cuenta por código.
POST	/api/admin/chart-of-accounts	Crea cuenta.
PUT	/api/admin/chart-of-accounts/:codigo	Actualiza nombre, descripción o jerarquía.
DELETE	/api/admin/chart-of-accounts/:codigo	Elimina cuenta.

Request

curl -X GET http://localhost:8000/api/admin/chart-of-accounts -b cookies.txt

Response 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" }
]

Empresa

Configuración única del tenant: RUT, razón social, giro, contacto y dirección. Solo dos métodos (lectura y actualización completa).

Método	Ruta	Uso
GET	/api/admin/company	Obtiene configuración de la empresa.
PUT	/api/admin/company	Actualiza datos (todos los campos opcionales).

Request

curl -X PUT http://localhost:8000/api/admin/company \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"razon_social": "Mi Empresa SpA", "direccion": "Av. Principal 123"}'

Response 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]"
}

Representantes Legales y Socios

Representantes legales, apoderados o socios firmantes de la empresa. Cada representante puede tener una cuenta corriente socio con saldo y movimientos; esa cuenta se activa o desactiva por separado del registro como representante.

Método	Ruta	Uso
GET	/api/admin/representatives	Lista representantes (?activeOnly=true para solo activos).
GET	/api/admin/representatives/:id	Detalle de un representante.
GET	/api/admin/representatives/:id/saldo-socio	Saldo de cuenta del socio asociado al representante.
GET	/api/admin/representatives/:id/movimientos-socio?anio=2026&mes=5	Movimientos de la cuenta del socio, con filtros opcionales.
POST	/api/admin/representatives	Crea representante (vigente queda false si no se informa).
PUT	/api/admin/representatives/:id	Actualiza datos del representante.
DELETE	/api/admin/representatives/:id	Elimina representante.
POST	/api/admin/representatives/:id/set-active (ADMIN)	Activa al representante como representante legal vigente.
POST	/api/admin/representatives/:id/activar-cuenta (ADMIN)	Activa la cuenta de socio asociada.
POST	/api/admin/representatives/:id/desactivar-cuenta (ADMIN)	Desactiva la cuenta de socio asociada.

Crear representante

curl -X POST http://localhost:8000/api/admin/representatives \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{
    "rut": "12345678-9",
    "nombres": "Juan",
    "apellidos": "Pérez González",
    "fecha_desde": "2026-05-01",
    "cargo": "Gerente General",
    "email": "[email protected]"
  }'

Response 201

{
  "id": "uuid-rep-1",
  "rut": "12345678-9",
  "nombres": "Juan",
  "apellidos": "Pérez González",
  "fecha_desde": "2026-05-01T00:00:00.000Z",
  "fecha_hasta": null,
  "vigente": false,
  "cargo": "Gerente General",
  "email": "[email protected]",
  "telefono": null,
  "direccion": null,
  "observaciones": null,
  "cuenta_contable_codigo": null,
  "tiene_cuenta_socio": false,
  "saldo_socio": null
}

Activar vigente

curl -X POST http://localhost:8000/api/admin/representatives/uuid-rep-1/set-active \
  -b cookies.txt

Movimientos socio

curl -X GET "http://localhost:8000/api/admin/representatives/uuid-rep-1/movimientos-socio?anio=2026&mes=5" \
  -b cookies.txt

Configuración del Sistema

Diccionario clave → valor para parámetros globales del tenant (año tributario, flags de notificación, etc.).

Método	Ruta	Uso
GET	/api/admin/system-config	Lista todas las configuraciones.
GET	/api/admin/system-config/:clave	Obtiene una configuración por clave.
PUT	/api/admin/system-config/:clave	Actualiza el valor de una clave.

Request

curl -X PUT http://localhost:8000/api/admin/system-config/tax_year \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"valor": "2026"}'

Response 200

{
  "clave": "tax_year",
  "valor": "2026",
  "actualizado_en": "2026-05-23T15:50:00Z"
}

Configuración Contable

CRUD sobre la configuración contable del tenant: el mapeo entre conceptos del sistema (ej. “IVA débito fiscal”, “remuneración líquida”, “ingreso por venta”) y las cuentas del plan contable que les corresponden. Es el cableado que permite a OperationsService y PayrollService generar asientos automáticamente.

Los endpoints usan cuentaCreateValidator, cuentaUpdateValidator, conceptoCreateValidator y conceptoUpdateValidator para validar payloads.

Cuentas

Método	Ruta	Uso
GET	/api/admin/config-contable/cuentas	Lista cuentas configuradas.
GET	/api/admin/config-contable/cuentas/:tipo	Cuenta(s) asociada(s) a un tipo.
POST	/api/admin/config-contable/cuentas	Crea configuración de cuenta.
PUT	/api/admin/config-contable/cuentas/:tipo	Actualiza configuración por tipo.
DELETE	/api/admin/config-contable/cuentas/:tipo	Elimina configuración.

Conceptos

Método	Ruta	Uso
GET	/api/admin/config-contable/conceptos	Lista conceptos contables.
GET	/api/admin/config-contable/conceptos/:codigo	Concepto por código.
POST	/api/admin/config-contable/conceptos	Crea concepto.
PUT	/api/admin/config-contable/conceptos/:codigo	Actualiza concepto.
DELETE	/api/admin/config-contable/conceptos/:codigo	Elimina concepto.

Listar conceptos

curl -X GET http://localhost:8000/api/admin/config-contable/conceptos -b cookies.txt

Response 200

{
  "success": true,
  "data": [
    {
      "codigo": "IVA_DEBITO",
      "descripcion": "IVA débito fiscal",
      "cuenta_codigo": "2.1.05"
    },
    {
      "codigo": "REMUN_LIQUIDA",
      "descripcion": "Remuneración líquida por pagar",
      "cuenta_codigo": "2.1.10"
    }
  ]
}

Notas de implementación

• Autenticación: todos los endpoints usan authenticateToken que valida el JWT desde la cookie sid.
• Roles: endpoints marcados con (ADMIN) usan requireRole(['ADMIN', 'SUPER_ADMIN']).
• Service Context: cada handler construye un ServiceContext con tenantDb, userId y requestId (header x-request-id) para tracing.
• Errores: el formato canónico de error es { "error": "Mensaje descriptivo" }. Códigos: 400 (validación), 401 (sin sesión), 403 (sin rol), 404 (no existe), 500 (error inesperado).