API y Webhooks

Aplica a: NominaHQ Roles: Crear claves de API y webhooks, y guardar la configuración de Integración: Nivel de acceso Acceso total o cuenta Administrador. Referencias regulatorias: Ley 81 de 2019 (protección de datos personales): las claves de API dan acceso a datos personales de los Empleados (Cédula, número de CSS, salario); guárdelas como un secreto.

Resumen

NominaHQ se conecta con otros sistemas de dos formas: una API REST para que sus sistemas lean datos de nómina (y registren marcaciones o calculen planillas), y Webhooks para que NominaHQ avise a sus sistemas cuando ocurre un evento, como una planilla pagada. Esta sección la usa el personal técnico que integra NominaHQ con relojes de asistencia, portales de RRHH o sistemas contables.

Navegación

Menú lateral: grupo Configuración, al final de la lista.

Las cuatro opciones para integraciones están juntas al final del grupo Configuración.

Conceptos clave

• Clave de API: secreto que su sistema envía en el encabezado X-Api-Key. Cada clave da acceso a una sola empresa: la que estaba activa al crearla.
• Webhook saliente: una URL suya a la que NominaHQ envía un POST firmado con HMAC-SHA256 cuando ocurre un evento (por ejemplo payroll.run.paid).
• Webhook entrante: mensajes que un sistema externo envía a NominaHQ en /api/v1/Webhooks/{source}.
• Documentación interactiva: la página /developers, que lista cada endpoint y permite probar llamadas con su clave.

Por dónde empezar

1. Para leer datos de NominaHQ desde otro sistema (Empleados, planillas, recibos, asientos contables): cree una clave en Claves de API y siga API REST.
2. Para recibir avisos cuando una planilla se aprueba, se paga o se contabiliza: registre su URL en Webhooks y siga Webhooks.
3. Para contabilizar en CifraHQ: use Integración y siga Contabilización en CifraHQ.

Páginas relacionadas

• API REST
• Webhooks
• Configuración inicial