Rutas disponibles

Este controlador está disponible a través de dos rutas alternativas:

Por Período

GET /v1/:company_id/periods/:period_id/bank_file_options

Utiliza el ID del período para obtener las opciones de archivo bancario.

Por Nómina

GET /v1/:company_id/payrolls/:payroll_id/bank_file_options

Utiliza el ID de la nómina para obtener las opciones de archivo bancario.

📘
Nota importante
Ambas rutas devuelven la misma estructura de respuesta y funcionan de manera idéntica. La diferencia radica en el parámetro utilizado para identificar el contexto:

period_id: Cuando deseas obtener opciones basadas en un período específico, son las opciones a consultar si con el archivo generado se le va a pagar a todos los empleados en un periodo

payroll_id: Cuando deseas obtener opciones basadas en una nómina específica, se usa si se va a realizar el pago de un empleado específico en casos de pago anticipado.

¿Qué hace este endpoint?

Este endpoint retorna las opciones de configuración disponibles para generar un archivo bancario (bank file) de dispersión de pagos. Las opciones devueltas son dinámicas y varían según el contenido del periodo o nómina consultada.

Alcance:

Para Period: Retorna opciones de contract_type (Nómina/Contratistas), locations (ubicaciones geográficas), y payment_type (tipos de pago disponibles)
Para Payroll individual: Retorna opciones de payment_type y payroll_range (rangos de pago anticipado, si aplica)
Incluye el nombre del banco configurado en bank_name

Qué NO hace:

No genera ni descarga el archivo bancario (eso lo hace el endpoint de BankFilesController)
No modifica ningún dato de la base de datos
No valida permisos bancarios ni saldos

Las opciones retornadas dependen de:

Si existen terminaciones en el periodo
Si hay beneficios sociales pagados (prima de servicios, cesantías)
Si hay trabajadores vs contratistas
Si el payroll tiene configurado pago anticipado
Las ubicaciones geográficas configuradas en la empresa

¿Cuándo usar este endpoint?

Antes de generar un archivo bancario para dispersión de pagos, para conocer qué opciones de filtrado están disponibles según el contenido del periodo/nómina
Cuando necesitas saber qué tipos de pagos puedes incluir en el archivo bancario (nómina regular, liquidaciones, prima de servicios, cesantías, o combinaciones)
Para filtrar la generación del archivo bancario por tipo de contrato (solo empleados de nómina vs solo contratistas)
Para segmentar los pagos por ubicación geográfica, cuando la empresa tiene sedes en diferentes ciudades y desea generar archivos bancarios separados
Para seleccionar rangos de pago anticipado, cuando un trabajador tiene vacaciones u otros conceptos con pago anticipado configurado

Consideraciones importantes

Permisos y autenticación:

Requiere autenticación JWT válida
Solo usuarios con rol administrador o contador pueden acceder
Usuarios tipo trabajador (worker) recibirán error 403 Forbidden
Organizadores externos (external organizer) recibirán error 403 Forbidden
Sin autenticación válida: error 401 Unauthorized

Requisitos previos:

La empresa debe tener al menos una cuenta bancaria configurada (company_bank_accounts). Sin esto, retorna error 422 Unprocessable Entity con código incomplete_bank_info
Si consultas un Payroll individual: el trabajador debe tener método de pago "Transferencia bancaria" (no efectivo ni cheque). Métodos de pago no bancarios retornan error 422 Unprocessable Entity con código worker_payment_type
Si consultas un Payroll individual de contratista: debe tener configurado pago anticipado válido. Sin esto, retorna error 422 Unprocessable Entity con código invalid_early_payment
El Period o Payroll consultado debe existir y pertenecer a la empresa: error 404 Not Found si no existe

Comportamiento:

Operación sincrónica e inmediata: Retorna las opciones al instante sin procesamiento asíncrono
Solo lectura: No modifica ningún registro en la base de datos
No guarda preferencias: Las opciones se calculan en tiempo real cada vez que se consulta el endpoint
Respuesta dinámica: El contenido de las opciones cambia según el estado actual del periodo/nómina

Opciones de payment_type disponibles:

Las opciones retornadas en payment_type dependen del contenido del periodo/nómina:

Valor	Descripción	Cuándo aparece
`payroll`	Solo nómina regular	Siempre disponible
`termination`	Solo liquidaciones	Si hay terminaciones en el periodo
`payroll_termination`	Nómina más liquidación (solo liquidados)	Si hay terminaciones en el periodo
`payroll_termination_full`	Nómina completa más liquidación	Solo para Period con terminaciones
`service_bonus`	Solo prima de servicios	Si hay primas pagadas
`severance_interests`	Solo intereses de cesantías	Si hay intereses de cesantías pagados
`social_benefit`	Prima e intereses de cesantías	Si hay ambos beneficios pagados
`payroll_service_bonus`	Nómina más prima	Si hay primas pagadas
`payroll_severance_interests`	Nómina más intereses de cesantías	Si hay intereses pagados
`payroll_social_benefit`	Nómina más prima e intereses	Si hay ambos beneficios pagados
`payroll_holidays`	Nómina más vacaciones	Si hay vacaciones con pago anticipado

Opciones de contract_type (solo Period):

payroll: Empleados de nómina regular (aparece si hay empleados en el periodo)
contractor: Contratistas (aparece si hay contratistas en el periodo)

Opciones de locations (solo Period):

company: Empresa (sin filtro de ubicación)
[location_id]: ID de cada ubicación geográfica configurada en la empresa

Opciones de payroll_range (solo Payroll con pago anticipado):

full_period: Periodo completo sin pago anticipado
[0, 1, 2, ...]: Índices de rangos de fechas para pago anticipado de vacaciones u otros conceptos

Límites y restricciones:

No aplica paginación (retorna todas las opciones disponibles)
No admite parámetros de filtrado en el request
Solo acepta método GET
Requiere que la empresa exista y el usuario tenga acceso a ella

Validaciones

1. Empresa sin cuenta bancaria configurada

Si la empresa no tiene cuentas bancarias registradas:

{
  "error": {
    "message": "Completa la información de tu empresa, ingresando un Banco y el número de cuenta.",
    "code": "0604",
    "object": "company"
  }
}

HTTP Status: 422 Unprocessable Entity
Código de error: incomplete_bank_info
Solución: Crear al menos una cuenta bancaria en company_bank_accounts antes de consultar este endpoint.

2. Trabajador con método de pago no bancario (solo nómina individual)

Si el trabajador del payroll tiene método de pago "Efectivo" o "Cheque":

{
  "error": {
    "message": "Esta persona tiene como medio de pago efectivo.",
    "code": "0605",
    "object": "worker"
  }
}

HTTP Status: 422 Unprocessable Entity
Código de error: worker_payment_type
Solución: Cambiar el método de pago del trabajador a "Transferencia bancaria" antes de generar archivos bancarios.

3. Nómina sin pago anticipado válido (contratistas)

Si consultas un payroll de contratista que no tiene pago anticipado configurado:

{
  "error": {
    "message": "Esta nómina no tiene pago anticipado.",
    "code": "1801",
    "object": "payroll"
  }
}

HTTP Status: 422 Unprocessable Entity
Código de error: invalid_early_payment
Solución: Configurar pago anticipado en el payroll o usar el endpoint de Period en lugar de Payroll individual.