Introducción a nominaHQ

¿Qué es nominaHQ?

nominaHQ es una plataforma en la nube, multi-empresa y multi-cliente, para procesar la nómina (planilla) de Panamá de principio a fin: cálculo de salarios, deducciones de ley, décimo, Vacaciones, Liquidación, declaración a la CSS (SIPE) y contabilización. Centraliza el cumplimiento laboral y fiscal panameño en una sola herramienta, con las tasas legales vigentes y configurables por fecha.

Está diseñada especialmente para proveedores de servicios de nómina (BPO y contadurías) que administran las planillas de muchas empresas cliente. El modelo es claro: el inquilino es el proveedor del servicio y las empresas dentro de él son sus clientes. Cada empresa tiene sus datos completamente aislados, y el operador cambia de cliente con el selector de empresa, administrando todas sus planillas desde un mismo acceso.

nominaHQ cubre el cumplimiento de Panamá: Seguro Social (CSS), Seguro Educativo, Impuesto Sobre la Renta (ISR), Décimo Tercer Mes, Vacaciones, Liquidación, exportación SIPE e integración contable con CifraHQ. Las tasas (incluida la rampa de la cuota patronal de la Ley 462) se manejan como configuración con vigencia por fecha, no como código.

Funcionalidades

El sistema se organiza en seis grandes módulos. A continuación se describe cada funcionalidad disponible.

1. Plataforma y Arquitectura

• Arquitectura multi-inquilino (multi-tenant) — Cada proveedor de nómina tiene su propia base de datos aislada, resuelta por subdominio. Los datos de un inquilino nunca se mezclan con los de otro.
• Multi-empresa con selector — Dentro de cada inquilino se administran múltiples empresas cliente. Toda la información está segregada por empresa y el operador cambia de cliente con el selector de la barra superior.
• Modelo de servicio de nómina (BPO) — Pensado para contadurías y BPO que ofrecen "nosotros llevamos su planilla" como servicio: el inquilino es el proveedor y las empresas internas son sus clientes.
• Autenticación segura — Inicio de sesión por cookie con expiración deslizante de 8 horas; contraseñas con hashing Argon2; usuarios del inquilino y un super-usuario administrador.
• Idioma base Español (Panamá) — Español de Panamá como idioma base; inglés opcional en /en; preferencia conservada por navegador.
• Marca y barra superior — Identidad nominaHQ con logo en el menú y la barra de la aplicación.
• Traducciones administrables — Catálogo de textos de la interfaz por idioma, editable desde Configuración → Traducciones.
• Gestión de usuarios — Alta y administración de usuarios del inquilino (administrador / usuario), con su idioma e información de acceso.

2. Datos maestros

• Empleados — Ficha, nombre, cédula/pasaporte, número de Seguro Social, fecha de ingreso, departamento, puesto, centro de costo, salario, frecuencia de pago y datos bancarios (ACH).
• Contratos de trabajo — Tipo (indefinido, definido, obra determinada), fechas, salario, jornada (diurna/nocturna/mixta), horas semanales y referencia MITRADEL.
• Departamentos — Estructura organizativa para agrupar y reportar Empleados por departamento.
• Puestos / Cargos — Catálogo de puestos, opcionalmente asociados a un departamento.
• Centros de Costo — Centros de costo jerárquicos para imputar el gasto de planilla.
• Conceptos de nómina — Ingresos, deducciones y aportes patronales, con banderas de afectación a CSS / Seguro Educativo / ISR y método de cálculo (fijo, porcentaje o motor).
• Parámetros legales (fechados) — CSS obrero/patronal, Seguro Educativo, tramos de ISR y CSS del décimo, con vigencia por fecha. Incluye la rampa de la Ley 462 (13.25% → 14.25% en 2027 → 15.25% en 2029).
• Configuración de Nómina por Empresa — Tasa de Riesgos Profesionales (por CIIU), número patronal SIPE, frecuencia por defecto y CSS del décimo.
• Salario mínimo (matriz MITRADEL) — Matriz nacional por región × actividad × ocupación × tamaño de empresa, con vigencia por fecha.

3. Motor de Cálculo

• Seguro Social (CSS) — Cuota obrera (9.75%) y patronal (13.25%, con rampa Ley 462) sobre la base afecta, según la tasa vigente del período.
• Seguro Educativo y Riesgos Profesionales — Seguro Educativo (1.25% obrero / 1.50% patronal) y Riesgos Profesionales patronal según el CIIU de la empresa.
• ISR con anualización — Anualiza el ingreso gravable, aplica la tabla progresiva (exento ≤ 11,000; 15%; 25%) y divide entre los períodos del año.
• Décimo Tercer Mes — 1/12 de lo devengado del cuatrimestre con CSS reducido (7.25%) y sin Seguro Educativo.
• Vacaciones — 30 días por cada 11 meses trabajados (un mes de salario por cada 11), en días y en valor.
• Liquidación — Prima de antigüedad (1 semana/año), indemnización (3.4 semanas/año hasta 10 años + 1 semana/año adicional), Vacaciones y décimo proporcional.

4. Procesamiento de Nómina

• Planillas (corridas) — Una entrada por empleado activo con ingresos, deducciones de ley y aportes patronales calculados automáticamente.
• Frecuencias de pago — Quincenal (15 y fin de mes), mensual y semanal, prorrateando el salario del período.
• Flujo de estados y aprobación — Borrador → Aprobada → Pagada → Contabilizada, controlando las acciones de cada etapa.
• Recibo de pago — Detalle agrupado en Ingresos, Deducciones, Salario Neto y Aportes Patronales, con la información congelada (inmutable).
• Corrida de Décimo Tercer Mes — Planilla de décimo por cuatrimestre (abril, agosto, diciembre) con CSS reducido.
• Calculadora de Liquidación — Empleado, fecha de terminación y causa → desglose completo del finiquito.
• Períodos contables — Años fiscales y períodos de pago para ordenar y cerrar la nómina.

5. Cumplimiento e integración contable

• Exportación SIPE (Carga Masiva) — Archivo de la planilla mensual de la CSS con número patronal, período y, por empleado, salario base y cuotas obrero/patronal de CSS y Seguro Educativo. Formato versionado.
• Contabilización al Mayor (GL) — Asiento contable balanceado (débito gasto y carga patronal; crédito neto y cuentas por pagar de CSS, Seguro Educativo, ISR y Riesgos), validando que cuadre.
• Envío a CifraHQ — El lote de diario se envía a CifraHQ por la integración de carga de asientos, con registro de cada intento.
• Mapa de Cuentas y Ajustes de Integración — Mapeo de cuentas contables (GL) y configuración de la integración con CifraHQ.

6. Plataforma para Desarrolladores

• API REST v1 — Consultar empresas, Empleados y planillas, y crear planillas. El inquilino se resuelve por el host y las consultas por empresa usan ?company={código}.
• Documentación interactiva (Scalar) — Documentación de la API en /developers: guía de inicio, autenticación, convenciones y ejemplos de código.
• Autenticación por API Key — Encabezado X-Api-Key; sin clave válida la respuesta es 401.
• Webhooks salientes — Notifican eventos (planilla aprobada/pagada/contabilizada, décimo) firmados con HMAC-SHA256 en X-NominaHQ-Signature.
• Webhooks entrantes — Reciben Webhooks de sistemas externos (bancos, relojes de marcación) en /api/v1/Webhooks/{source}.
• Registro de entregas — Bitácora de cada intento de entrega de webhook (evento, URL, código HTTP, duración y error).
• Protección contra SSRF — Bloquea destinos no públicos (loopback, redes privadas, metadatos de nube) validando la IP al conectar y sin redirecciones automáticas.