🔍 ¿Qué hace este endpoint?

Genera el archivo de seguridad social del periodo especificado y retorna la URL de descarga del archivo generado. El archivo contiene la información de aportes a seguridad social (salud, pensión, ARL) de los trabajadores del periodo. Admite generación síncrona (retorna inmediatamente la URL) o asíncrona (procesa en background y notifica vía websocket cuando esté listo). Permite generar el archivo en formato de texto plano (.txt) o como resumen en formato Excel (.xlsx).

🎯 ¿Cuándo usar este endpoint?

Cuando se requiere generar el archivo de planilla PILA para realizar el pago de seguridad social.
Cuando se necesita descargar el archivo TXT estándar para cargar en el sistema PILA.
Cuando se requiere un resumen en Excel de la planilla de seguridad social para revisión interna.
Cuando se necesita generar el archivo para una sucursal específica de seguridad social.
Cuando se necesita generar el archivo de forma asíncrona para evitar timeouts en periodos con muchos trabajadores.

📌 Consideraciones importantes

Permisos y autenticación

Requiere autenticación mediante token Bearer.
El usuario debe tener acceso a la empresa especificada en company_id.
El periodo debe existir y pertenecer a la empresa.
Retorna 401 No autorizado si el token es inválido o ha expirado.
Retorna 403 No autorizado si el usuario no tiene permisos para acceder a la empresa.
Retorna 402 Pago requerido si la empresa no tiene suscripción activa.
Retorna 404 No encontrado si el periodo no existe o no pertenece a la empresa.
Retorna 422 No procesable si hay contratos sin terminar el registro o si no se ha configurado una sucursal de seguridad social.

Sucursal de seguridad social

Si se proporciona el parámetro social_security_branch_id, debe corresponder a una sucursal de seguridad social válida de la empresa.
Retorna 404 No encontrado si la sucursal especificada no existe o no pertenece a la empresa.
Si no se proporciona, se usa la sucursal por defecto de la empresa.

Parámetros de generación

file_type (opcional): Tipo de archivo a generar. Valores permitidos: txt (por defecto) o xlsx. El formato TXT es el estándar requerido por PILA, mientras que XLSX es un resumen para revisión.
social_security_branch_id (opcional): ID de la sucursal de seguridad social a usar para la generación. Si no se especifica, se usa la sucursal configurada por defecto para la empresa.
async (opcional): Si es true, la generación se realiza de forma asíncrona mediante un job en background. Por defecto false (generación síncrona). Se recomienda usar async=true para periodos con muchos empleados para evitar timeouts.
form_type (opcional): Tipo de formulario a usar en la generación. Por defecto employee.

Respuesta

Retorna un objeto JSON con el campo file que contiene la URL de descarga del archivo generado.
La URL es temporal y expira después de un tiempo determinado.
El nombre del archivo incluye el nombre de la empresa y el tipo de archivo (TXT o XLSX).

Validaciones previas

El periodo debe existir y estar asociado a la empresa.
Todos los contratos del periodo deben tener el registro completado.
Debe existir una sucursal de seguridad social configurada (ya sea la especificada en el parámetro o la por defecto).
La empresa debe tener suscripción activa.

Variaciones en la respuesta

La respuesta siempre contiene el campo file con la URL de descarga, independientemente del formato solicitado. La URL es temporal y expira después de un tiempo determinado.

Ejemplo con file_type=txt (o sin especificar):

{
  "file": "https://api.aleluya.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJqYXk5MHM0cng3N3BpYmVybzRwODNwbHF4YTlkIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cIkVuZXJvX2ZvcnRuaWdodGx5X2NvbXBhbnlfU2VndXJpZGFkU29jaWFsLnR4dFwiOyBmaWxlbmFtZSo9VVRGLTgnJ0VuZXJvX2ZvcnRuaWdodGx5X2NvbXBhbnlfU2VndXJpZGFkU29jaWFsLnR4dCIsImNvbnRlbnRfdHlwZSI6InRleHQvcGxhaW4iLCJzZXJ2aWNlX25hbWUiOiJ0ZXN0In0sImV4cCI6IjIwMjQtMDctMDNUMTk6Mjk6NDUuMzc1WiIsInB1ciI6ImJsb2Jfa2V5In19--47fc588f00e223f5f4a9d8c5b44f2fe4504f87d3/Enero_fortnightly_company_SeguridadSocial.txt"
}

Ejemplo con file_type=xlsx:

{
  "file": "https://api.aleluya.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJqYXk5MHM0cng3N3BpYmVybzRwODNwbHF4YTlkIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cIkVuZXJvX2ZvcnRuaWdodGx5X2NvbXBhbnlfU2VndXJpZGFkU29jaWFsLnR4dFwiOyBmaWxlbmFtZSo9VVRGLTgnJ0VuZXJvX2ZvcnRuaWdodGx5X2NvbXBhbnlfU2VndXJpZGFkU29jaWFsLnR4dCIsImNvbnRlbnRfdHlwZSI6InRleHQvcGxhaW4iLCJzZXJ2aWNlX25hbWUiOiJ0ZXN0In0sImV4cCI6IjIwMjQtMDctMDNUMTk6Mjk6NDUuMzc1WiIsInB1ciI6ImJsb2Jfa2V5In19--47fc588f00e223f5f4a9d8c5b44f2fe4504f87d3/Enero_fortnightly_company_SeguridadSocial.xlsx"
}