P4 Software / NominaHQ

API REST

API REST

Aplica a: NominaHQ Roles: cualquier usuario autenticado del personal puede crear, listar y revocar claves de API para la empresa activa en Configuración → API Keys. Cada clave otorga acceso solo a la empresa para la que se creó. Referencias regulatorias: ninguna directa. Las planillas que se calculen por la API aplican las reglas de Panamá (CSS, ISR, Código de Trabajo) del motor de nómina.

Resumen

La API REST de NominaHQ permite leer y automatizar datos de nómina de Panamá desde sistemas externos: empresa, Empleados, planillas (payroll runs) y los lotes de diario contable. Está pensada principalmente para lectura e integración — por ejemplo, relojes de asistencia u otros sistemas externos que necesitan escribir o consultar datos de una empresa cliente específica. Cada llamada se autentica con una clave enviada en el encabezado X-Api-Key, y esa clave identifica una sola empresa — nunca todo el inquilino. La documentación interactiva se publica en /developers.

Navegación

  • Documentación interactiva (Scalar): menú Configuración → API Desarrolladores, que abre la ruta /developers.
  • Administración de claves: menú Configuración → API Keys, ruta /settings/api-keys.
  • La página de Perfil (ruta /profile) tiene un enlace directo a /settings/api-keys y a /developers.

Conceptos clave

  • Inquilino (tenant): el proveedor de servicios de nómina. Se resuelve a partir del host (subdominio) que usted llama, por ejemplo https://{su-inquilino}.NominaHQ.cloud.
  • Empresa (company / cliente): cada cliente del inquilino. Cada clave de API se crea para una empresa específica (la empresa activa en el momento de crearla) y solo da acceso a los datos de esa empresa.
  • Planilla (payroll run): la corrida de nómina de una empresa para un período. Su frecuencia puede ser Quincenal, Mensual o Semanal.
  • Lote de diario (journal batch): el asiento contable que NominaHQ genera al contabilizar una planilla o un Décimo, con sus líneas de débito y crédito. Consultarlo por la API permite que un ERP externo traiga (pull) los diarios de nómina, en vez de esperar a que NominaHQ se los envíe.
  • X-Api-Key: encabezado HTTP donde se envía la clave de API en cada solicitud.
  • Scalar: interfaz de documentación de la API publicada en /developers, basada en el documento OpenAPI (/openapi/v1.json).
  • Webhook: notificación que NominaHQ envía a un sistema externo cuando ocurre un evento (se configura aparte; ver Funciones relacionadas).

Paso a paso

Crear una clave de API

  1. Seleccione la empresa para la que necesita la clave (selector de empresa activa).
  2. Vaya a Configuración → API Keys (ruta /settings/api-keys).
  3. Presione New, escriba una Label descriptiva (ej. "Reloj de asistencia — bodega") y presione Create.
  4. Copie la clave mostrada de inmediato — no se vuelve a mostrar. Presione Done al terminar.
  5. Si necesita otra empresa, cambie la empresa activa y repita — cada clave queda ligada a la empresa que estaba activa al crearla.

Hacer una llamada de lectura

  1. Construya la URL con su subdominio de inquilino, por ejemplo https://{su-inquilino}.NominaHQ.cloud/api/v1/companies.
  2. Agregue el encabezado X-Api-Key con su clave. Sin clave válida o revocada, la respuesta es 401 Unauthorized.
  3. No hay parámetro de empresa: la clave ya determina la empresa.
  4. Lea la respuesta JSON. Los montos son decimales en USD ($) con 2 decimales; las fechas son ISO-8601 y las horas en UTC.

Ejemplo:

curl https://{su-inquilino}.NominaHQ.cloud/api/v1/companies -H "X-Api-Key: YOUR_API_KEY"

Traer los diarios de nómina a su ERP (pull)

  1. Pida la lista de lotes con GET /api/v1/journal-batches. Devuelve los 100 más recientes de la empresa de la clave, del más nuevo al más antiguo, sin las líneas.
  2. Para traer solo los que aún no ha contabilizado, agregue el filtro ?status=Pending. Los valores admitidos son Pending, Sent, Confirmed y Failed; cualquier otro devuelve 400.
  3. Si necesita más de 100 lotes (por ejemplo, al conectar el ERP por primera vez con historial acumulado), pagine con ?skip=100, ?skip=200, etc., o acote por fecha de contabilización con ?from=2026-01-01&to=2026-06-30. Cuando una página devuelve menos de 100 lotes, ya no hay más.
  4. Por cada lote que le interese, pida su detalle con GET /api/v1/journal-batches/{id}. La respuesta agrega el arreglo lines con las líneas de débito y crédito.
  5. Registre el id de los lotes ya procesados en su ERP: es lo que evita importar dos veces el mismo asiento.
curl "https://{su-inquilino}.NominaHQ.cloud/api/v1/journal-batches?status=Pending" -H "X-Api-Key: YOUR_API_KEY"
curl https://{su-inquilino}.NominaHQ.cloud/api/v1/journal-batches/{id} -H "X-Api-Key: YOUR_API_KEY"

Revocar una clave

  1. Vaya a Configuración → API Keys.
  2. Presione Revoke junto a la clave. Queda inactiva de inmediato — cualquier llamada con esa clave recibirá 401.

Referencia de endpoints

Método Ruta Descripción
GET /api/v1/companies Devuelve la única empresa a la que está ligada la clave presentada.
GET /api/v1/employees Lista los Empleados de la empresa de la clave, ordenados por código.
GET /api/v1/payroll-runs Lista las planillas de la empresa de la clave, de la más reciente a la más antigua.
POST /api/v1/payroll-runs Calcula una planilla (quincenal/mensual/semanal) para la empresa de la clave, en el período indicado; puede aprobarla en la misma llamada.
GET /api/v1/journal-batches Lista hasta 100 lotes de diario de la empresa de la clave, del más reciente al más antiguo, sin las líneas. Filtros opcionales: ?status=Pending|Sent|Confirmed|Failed, ventana de fechas ?from=/?to= (fecha de contabilización, formato ISO) y paginación con ?skip=.
GET /api/v1/journal-batches/{id} Devuelve un lote de diario de la empresa de la clave, con sus líneas de débito y crédito.

Nota: la API no pagina, con una excepción: /journal-batches devuelve páginas de hasta 100 lotes y admite ?skip= y la ventana ?from=/?to= para recorrer el resto. La versión va en la ruta (/api/v1); los cambios incompatibles se publican bajo una versión nueva.

Referencia de campos

Respuesta — empresa (/api/v1/companies)

Campo Tipo Descripción
id GUID Identificador de la empresa.
code Texto Código de la empresa.
name Texto Nombre de la empresa.
baseCurrency Texto Moneda base.
isActive Booleano Indica si la empresa está activa.

Respuesta — empleado (/api/v1/employees)

Campo Tipo Descripción
id GUID Identificador del empleado.
code Texto Código/ficha del empleado.
firstName Texto Nombre.
lastName Texto Apellido.
nationalId Texto Cédula (puede venir vacío).
cssNumber Texto Número de Seguro Social/CSS (puede venir vacío).
monthlySalary Decimal (USD) Salario mensual.
payFrequency Texto Frecuencia de pago del empleado.
status Texto Estado del empleado.
isActive Booleano Indica si el empleado está activo.

Respuesta — planilla (/api/v1/payroll-runs)

Campo Tipo Descripción
id GUID Identificador de la planilla.
runType Texto Tipo de corrida.
frequency Texto Frecuencia (Quincenal/Mensual/Semanal).
periodStart Fecha Inicio del período.
periodEnd Fecha Fin del período.
payDate Fecha Fecha de pago.
status Texto Estado de la planilla.
entryCount Entero Cantidad de líneas (Empleados).
totalGross Decimal (USD) Total devengado.
totalDeductions Decimal (USD) Total de deducciones.
totalEmployerCost Decimal (USD) Costo patronal total.
totalNet Decimal (USD) Neto a pagar.

Respuesta — lote de diario (/api/v1/journal-batches y `/api/v1/journal-batches/

Campo Tipo Descripción
id GUID Identificador del lote. Es el valor que se usa en /journal-batches/{id} y el que conviene guardar en el ERP para no importar dos veces el mismo asiento.
eventType Texto Evento que originó el lote: Payroll, Decimo, PayrollDisbursement, Provisions o CesantiaDeposit.
sourceId GUID Identificador del documento de origen (la planilla o la corrida de Décimo que se contabilizó).
postedDate Fecha Fecha de contabilización del asiento.
status Texto Pending, Sent, Confirmed o Failed.
totalDebit Decimal (USD) Total al débito.
totalCredit Decimal (USD) Total al crédito. Siempre igual a totalDebit.
lines Arreglo Líneas del asiento. Viene vacío (null) en la lista y solo se llena al pedir un lote por su id.

Cada elemento de lines:

Campo Tipo Descripción
accountCode Texto Código de la cuenta contable.
debit Decimal (USD) Monto al débito de la línea.
credit Decimal (USD) Monto al crédito de la línea.
description Texto Descripción de la línea (puede venir vacía).

Solicitud — crear planilla (POST /api/v1/payroll-runs)

Campo Tipo Obligatorio Descripción Validación
periodStart Fecha (ISO-8601) Sí Inicio del período. —
periodEnd Fecha (ISO-8601) Sí Fin del período. —
payDate Fecha (ISO-8601) Sí Fecha de pago. —
frequency Entero Sí Frecuencia: 0 = Quincenal, 1 = Mensual, 2 = Semanal. Debe ser un valor válido.
description Texto Opcional Descripción de la planilla. —
approve Booleano Sí Si es true, aprueba la planilla además de calcularla. —

Respuesta correcta: { "runId": "<GUID>" }. Si el motor rechaza el cálculo (regla de negocio), la respuesta es 400 con { "error": "mensaje" }.

Formato de error

Todas las respuestas de error usan la forma { "error": "mensaje" } con el estado HTTP correspondiente: 400 (solicitud inválida, filtro status no reconocido o rechazo de regla de negocio), 401 (clave faltante, inválida o revocada), 404 (empresa no encontrada —solo posible si la empresa de la clave fue eliminada— o lote de diario inexistente).

Roles y permisos

Rol Crear/revocar claves (en la app) Llamar a la API (con una clave)
FullAccess Sí Sí
DataEntry Sí Sí
Approver Sí Sí
ViewOnly Sí Sí
Administrador Sí Sí

Notas:

  • Cada clave otorga acceso solo a la empresa para la que se creó — no a otras empresas del mismo inquilino.
  • La clave completa solo se muestra una vez, en el momento de crearla. NominaHQ solo guarda su huella (hash); si la pierde, revóquela y cree una nueva.
  • Trate cada clave como un secreto: no la incruste en aplicaciones de cliente ni la comparta fuera de canales seguros.

Notas de cumplimiento

  • La API en sí es técnica y no impone reglas regulatorias propias. Las planillas creadas mediante POST /api/v1/payroll-runs se calculan con el motor de nómina, que aplica CSS (empleado 9.75% / empleador 13.25%), Seguro Educativo, ISR por tramos y el resto de las reglas del Código de Trabajo de Panamá.
  • La clave de X-Api-Key otorga acceso a datos personales (Cédula, CSS) y a la creación de planillas para su empresa. Manténgala del lado del servidor y nunca la incruste en aplicaciones de cliente.

Solución de problemas

Síntoma Causa probable Solución
401 con {"error":"Missing or invalid X-Api-Key."} Falta el encabezado X-Api-Key, la clave es incorrecta, o fue revocada. Cree una nueva clave en Configuración → API Keys y envíela en el encabezado X-Api-Key.
404 con {"error":"Company not found."} (solo en POST /payroll-runs) La empresa a la que estaba ligada la clave fue eliminada. Cree una nueva clave para una empresa activa.
400 al crear una planilla El motor rechazó el cálculo por una regla de negocio. Lea el mensaje de error, corrija fechas/frecuencia/datos y reintente.
400 con {"error":"Invalid status. Use Pending, Sent, Confirmed or Failed."} El filtro ?status= trae un valor que no existe (por ejemplo, en español). Use exactamente Pending, Sent, Confirmed o Failed.
404 con {"error":"Journal batch not found."} El id no corresponde a ningún lote, o el lote pertenece a otra empresa. Tome el id de la respuesta de GET /api/v1/journal-batches y confirme que usa la clave de la empresa dueña del lote.
GET /journal-batches responde con la lista vacía Ninguna corrida de esa empresa se ha contabilizado todavía. Contabilice una corrida con Post to GL en Nómina → Planillas.
Los lotes traen lines vacío La lista nunca incluye las líneas. Pida cada lote por separado con GET /api/v1/journal-batches/{id}.
El servidor mostrado en /developers no es su subdominio El host se resuelve de la solicitud actual. Abra /developers desde la URL de su propio inquilino (https://{su-inquilino}.NominaHQ.cloud).

Funciones relacionadas

  • Webhooks (Configuración → Webhooks): reciba eventos como payroll.run.posted, payroll.run.approved, payroll.run.paid y decimo.posted, con firma HMAC X-NominaHQ-Signature. También puede recibir Webhooks entrantes con POST /api/v1/Webhooks/{source}.
  • Integración (Configuración → Integración): contabilización a CifraHQ.
  • Contabilización (Nómina → Lotes de Diario): además del pull por la API, cada lote se puede descargar a mano en CSV o XLSX con un diseño genérico para otros ERP.
  • Planilla (Nómina): cálculo y aprobación de planillas desde la interfaz.

¿Te resultó útil esta página?

Anterior API y Webhooks Siguiente Webhooks