P4 Software P4 Software / NominaHQ

Agrega esta documentación a Claude

Hazle preguntas a Claude sobre esta documentación. Claude lee las páginas publicadas y te enlaza a ellas. Copia esta dirección:

https://docs.p4software.cloud/mcp

En claude.ai o Claude Desktop: abre Configuración, luego Conectores, elige Agregar conector personalizado y pega la dirección.

En Claude Code, ejecuta:

claude mcp add --transport http docs https://docs.p4software.cloud/mcp

API REST

API REST

Aplica a: NominaHQ Roles: Crear y revocar claves de API: Nivel de acceso Acceso total o cuenta Administrador (los demás usuarios ven la lista, sin los botones Nuevo ni Revocar). 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

  • Administración de claves: menú Configuración → Claves de API (ruta /settings/api-keys).
  • Documentación interactiva (Scalar): menú Configuración → API para desarrolladores, que abre la ruta /developers.
  • La página Mi Perfil (menú de su nombre → Perfil) tiene enlaces directos a Claves de API y a la documentación de la API.

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, Semanal o Bisemanal (cada 14 días).
  • 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).

Tarea 1 — Crear una clave de API

Antes de empezar: seleccione en la barra superior la empresa para la que necesita la clave: la clave queda ligada a la empresa activa al crearla. Necesita el rol Acceso total.

  1. En el menú lateral, dentro de Configuración, haga clic en Claves de API.

    Pantalla Claves de API con la lista de claves y la opción Claves de API del menú resaltada

    La lista muestra la Etiqueta, el inicio de la Clave, el Estado, el Último uso y la fecha de creación de cada clave de la empresa activa.

  2. Haga clic en Nuevo.

    Botón Nuevo resaltado en la parte superior de Claves de API

    Se abre el cuadro Nueva Clave de API.

  3. En Etiqueta, escriba para qué es la clave (en el ejemplo, Documentación (demo); en la práctica, por ejemplo "Reloj de asistencia — bodega").

    Cuadro Nueva Clave de API con el campo Etiqueta resaltado

    La etiqueta le ayuda a saber qué integración revocar si algún día hace falta.

  4. Haga clic en Crear.

    Cuadro Nueva Clave de API con el botón Crear resaltado

    Crear se habilita cuando la Etiqueta tiene valor.

  5. Copie la clave con Copiar y guárdela en un lugar seguro (el gestor de secretos de su integración).

    Recuadro Copie su nueva clave de API ahora — no se volverá a mostrar, con la clave oculta y el botón Copiar resaltado

    La clave completa solo se muestra esta vez. En la captura aparece oculta a propósito.

  6. Haga clic en Listo.

    Recuadro de la nueva clave con el botón Listo resaltado

    El recuadro se cierra y la clave ya no se puede volver a ver.

Resultado: aparece "Clave de API creada" y la clave se agrega a la lista como Activo. Para otra empresa, cambie la empresa activa y repita.

Tarea 2 — Revocar una clave

  1. En la lista, haga clic en Revocar junto a la clave.

    Lista de claves con el botón Revocar de la fila Documentación (demo) resaltado

    Revoque una clave cuando deje de usar la integración o sospeche que se filtró.

  2. Confirme con Confirmar.

    Cuadro de confirmación Revocar con el botón Confirmar resaltado

    El cuadro muestra la etiqueta de la clave que va a revocar. Con Cancelar se cierra sin revocar.

  3. Revise la lista: la clave queda en estado Revocada.

    Fila Documentación (demo) resaltada con el estado Revocada

    Las claves revocadas se quedan en la lista como historial; no se pueden reactivar ni borrar.

Resultado: la clave deja de funcionar de inmediato: cualquier llamada con ella recibe 401.

Tarea 3 — Abrir la documentación interactiva

  1. En el menú lateral, dentro de Configuración, haga clic en API para desarrolladores.

    Menú Configuración con la opción API para desarrolladores resaltada debajo de Claves de API

    Se abre la documentación de la API en la ruta /developers.

  2. Use la documentación: el panel izquierdo lista los endpoints; Server muestra la dirección de su cuenta; Download OpenAPI Document descarga la especificación.

    Página nominaHQ API (Scalar) con la lista de endpoints, el servidor https://acme.nominahq.cloud y la sección Authentication

    La documentación está en inglés. Con Open API Client puede probar llamadas escribiendo su clave en Authentication.

Usar la API

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"

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.
POST /api/v1/time-clock-entries Crea marcaciones del reloj (entrada/salida por empleado y fecha) en lote; aplica la misma detección de tardanzas que la captura manual.
GET /api/v1/payroll-runs/{id} Devuelve una planilla con todos sus recibos (bruto, deducciones, aportes patronales, neto). Agregue ?lines=true para incluir las líneas de concepto de cada recibo.
GET /api/v1/payslips/{id} Devuelve un recibo con sus líneas de concepto.
GET /api/v1/payslips/{id}/pdf Descarga el recibo en PDF, igual al que ven operadores y Empleados.
GET /api/v1/payroll-runs/{id}/planilla Descarga el resumen de la planilla en Excel.
GET /api/v1/payroll-runs/{id}/sipe Descarga el archivo SIPE «Carga Masiva de Planilla» de la CSS (plan Business o superior; si no, responde 402).
GET /api/v1/payroll-runs/{id}/planilla03 Descarga el Informe 03 V5 de la DGI. Opcional ?receipt= con el número de recibo SIPE.
GET /api/v1/payroll-runs/{id}/ach Descarga el archivo de dispersión bancaria (ACH) del neto en el formato bancario configurado para la empresa (plan Business o superior). Si algún pago sería rechazado por la red ACH, responde 422 con la lista de Empleados a corregir.

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/Bisemanal).
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, 3 = Bisemanal (cada 14 días). 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)
Administrador Sí Sí
Acceso total Sí Sí
Captura de datos No (solo ve la lista) Sí
Aprobador No (solo ve la lista) Sí
Solo lectura No (solo ve la lista) Sí

La API no usa el rol de la persona: quien tenga una clave activa accede a los datos de su empresa.

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 → Claves de API 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