Query API Reference

Overview

Los endpoints Query son de solo lectura (GET) y retornan datos del tenant actual. Todos requieren autenticación via JWT cookie.

Base URL: http://localhost:8000/api/query

Headers requeridos:

Cookie: sid=<JWT_TOKEN>
Content-Type: application/json

---

Employees

GET /api/query/employees

Lista todos los empleados del tenant.

Request

curl -X GET http://localhost:8000/api/query/employees \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "rut": "12.345.678-9",
      "nombre": "Juan Pérez",
      "apellido_paterno": "Pérez",
      "apellido_materno": "González",
      "email": "[email protected]",
      "fecha_nacimiento": "1985-03-15",
      "fecha_ingreso": "2020-01-15",
      "cargo_id": 5,
      "departamento_id": 2,
      "active": true
    }
  ],
  "count": 1
}

GET /api/query/employees/:id

Obtiene un empleado específico.

Request

curl -X GET http://localhost:8000/api/query/employees/1 \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": {
    "id": 1,
    "rut": "12.345.678-9",
    "nombre": "Juan Pérez",
    "contracts": [
      {
        "id": 10,
        "tipo_contrato": "indefinido",
        "fecha_inicio": "2020-01-15",
        "fecha_termino": null,
        "sueldo_base": 1500000
      }
    ]
  }
}

Response 404

{
  "success": false,
  "error": "Employee not found"
}

---

Contracts

GET /api/query/contracts

Lista contratos con filtros opcionales.

Query params:

• employee_id: Filtrar por empleado
• active: true para solo contratos vigentes
• tipo: Tipo de contrato (indefinido, plazo_fijo, etc.)

Request

curl -X GET "http://localhost:8000/api/query/contracts?active=true" \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 10,
      "employee_id": 1,
      "employee_name": "Juan Pérez",
      "tipo_contrato": "indefinido",
      "fecha_inicio": "2020-01-15",
      "fecha_termino": null,
      "sueldo_base": 1500000,
      "jornada": "completa"
    }
  ],
  "count": 1
}

---

Payroll

GET /api/query/payroll

Lista nóminas procesadas.

Query params:

• year: Año (requerido)
• month: Mes (requerido)
• employee_id: Filtrar por empleado (opcional)

Request

curl -X GET "http://localhost:8000/api/query/payroll?year=2026&month=1" \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 100,
      "employee_id": 1,
      "employee_name": "Juan Pérez",
      "year": 2026,
      "month": 1,
      "sueldo_base": 1500000,
      "total_haberes": 1650000,
      "total_descuentos": 320000,
      "liquido": 1330000,
      "status": "calculated"
    }
  ],
  "summary": {
    "total_haberes": 1650000,
    "total_descuentos": 320000,
    "total_liquido": 1330000
  }
}

---

Departments

GET /api/query/departments

Lista departamentos/áreas.

Request

curl -X GET http://localhost:8000/api/query/departments \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "Gerencia General",
      "codigo": "GG",
      "parent_id": null,
      "employee_count": 3
    },
    {
      "id": 2,
      "nombre": "Recursos Humanos",
      "codigo": "RRHH",
      "parent_id": 1,
      "employee_count": 5
    }
  ]
}

---

Cargos

GET /api/query/cargos

Lista cargos/posiciones laborales.

Request

curl -X GET http://localhost:8000/api/query/cargos \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "Gerente General",
      "nivel": 1,
      "departamento_id": 1
    },
    {
      "id": 5,
      "nombre": "Analista de RRHH",
      "nivel": 3,
      "departamento_id": 2
    }
  ]
}

---

Common (Parámetros del Sistema)

GET /api/query/common/indicadores

Obtiene indicadores económicos (UF, UTM, IPC).

Request

curl -X GET "http://localhost:8000/api/query/common/indicadores?year=2026&month=1" \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": {
    "uf": 37500.50,
    "utm": 65000.00,
    "ipc": 0.3,
    "sueldo_minimo": 500000,
    "tope_imponible_afp": 2500000,
    "tope_imponible_salud": 2500000
  }
}

GET /api/query/common/afp

Lista AFPs activas.

Request

curl -X GET http://localhost:8000/api/query/common/afp \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "Capital",
      "tasa": 11.44,
      "sis": 1.85
    },
    {
      "id": 2,
      "nombre": "Cuprum",
      "tasa": 11.44,
      "sis": 1.85
    }
  ]
}

GET /api/query/common/isapres

Lista ISAPREs activas.

Request

curl -X GET http://localhost:8000/api/query/common/isapres \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "Fonasa",
      "codigo": "FON",
      "tipo": "publica"
    },
    {
      "id": 2,
      "nombre": "Colmena",
      "codigo": "COL",
      "tipo": "privada"
    }
  ]
}

---

Company

GET /api/query/company

Obtiene datos de la empresa del tenant actual.

Request

curl -X GET http://localhost:8000/api/query/company \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": {
    "id": 1,
    "rut": "76.123.456-7",
    "razon_social": "Empresa Demo SpA",
    "nombre_fantasia": "Demo",
    "giro": "Servicios de Software",
    "direccion": "Av. Providencia 1234",
    "comuna": "Providencia",
    "telefono": "+56 2 1234 5678",
    "email": "[email protected]",
    "representante_legal": {
      "rut": "12.345.678-9",
      "nombre": "Carlos González"
    }
  }
}

---

Declaraciones

GET /api/query/declaraciones

Lista declaraciones juradas generadas.

Query params:

• year: Año
• tipo: f29, dj1879, dj1887

Request

curl -X GET "http://localhost:8000/api/query/declaraciones?year=2026&tipo=f29" \
  -H "Cookie: sid=$JWT_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 50,
      "tipo": "f29",
      "periodo": "2026-01",
      "status": "generated",
      "generated_at": "2026-02-05T10:30:00Z",
      "total_impuesto": 450000
    }
  ]
}

---

Error Responses

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": "Mensaje descriptivo del error",
  "code": "ERROR_CODE"
}

Códigos de Error Comunes

Code	HTTP	Descripción
UNAUTHORIZED	401	Token faltante o inválido
FORBIDDEN	403	Sin permisos para este recurso
NOT_FOUND	404	Recurso no existe
VALIDATION_ERROR	400	Parámetros inválidos
INTERNAL_ERROR	500	Error del servidor

---

Pagination

Endpoints que retornan listas soportan paginación:

curl -X GET "http://localhost:8000/api/query/employees?page=2&limit=20" \
  -H "Cookie: sid=$JWT_TOKEN"

Response:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

---

Related Documentation

• API Patterns - Arquitectura y patrones
• Command Endpoints - Endpoints de escritura
• Admin Endpoints - Endpoints administrativos

---

Changelog

Fecha	Version	Cambios
2026-01-18	1.0	Referencia inicial creada