Descripción de la Plataforma

Acerca de Aleluya API

Aleluya API permite a desarrolladores, empresas e integradores construir soluciones de nómina y gestión de recursos humanos que se integren directamente con la plataforma de Aleluya.

Esta guía está diseñada para cualquier persona o equipo que desee integrar funcionalidades de nómina colombiana en sus aplicaciones, ofreciendo las herramientas y flexibilidad necesarias para crear experiencias seguras, conformes con la regulación local y de clase mundial en Colombia.

¿Qué puedes construir?

Gestión de empresas

Configura y mantén la información centralizada de la empresa, eje vertebral de toda operación en Aleluya.

Capacidades clave:

Onboarding de empresa con datos legales y tributarios.
Configuración de número de identificación y tipo de documento.
Gestión de múltiples centros de trabajo y ubicaciones.
Configuración de métodos de pago (PSE, débito automático, tarjeta de crédito/débito).
Gestión de cuentas bancarias para dispersión de nómina.
Configuración de periodos de pago (mensual, quincenal).
Almacenamiento centralizado de documentos (máx. 1MB por archivo).
Integración con software contable (Alegra, Siigo).

Gestión de nómina

Automatiza todos los aspectos de la liquidación de nómina, con cumplimiento automático de normativa colombiana (DIAN, UGPP).

Capacidades clave:

Liquidación de nómina mensual y quincenal.
Nóminas electrónicas con transmisión automática a DIAN.
Cálculo automático de retención en la fuente.
Liquidaciones de prestaciones sociales (cesantías, prima de servicios, vacaciones).
Terminaciones laborales con cálculos de liquidación.
Generación de reportes y certificados laborales.
Descarga de interfaz contable para sistemas contables.
Descarga de archivos para pago bancario.

Gestión de seguridad social

Simplifica la afiliación, pago y gestión de seguridad social (EPS, ARL, AFP, CCF) desde un único lugar.

Capacidades clave:

Afiliación automática a fondos de seguridad social.
Pago de aportes a seguridad social (PILA).
Reclamación de incapacidades ante EPS y ARL.
Descarga de información exógena.
Validación de afiliaciones y estados vigentes.
Archivos UGPP para procesos especiales

Gestión de personas y contratistas

Completo ciclo de vida de las personas contratadas por una empresa: desde onboarding hasta terminación.

Capacidades clave:

Onboarding de personas contratadas por una empresa.
Gestión de tipos de contrato (término indefinido, fijo, por obra o labor, aprendices, pasantías).
Configuración de salarios y conceptos recurrentes.
Gestión de préstamos o deducciones personalizadas.
Control de vacaciones, licencias e incapacidades.
Descarga de certificados laborales y de ingresos.
Portal de autogestión para personas (acceso a desprendibles, certificados, historial de pagos).

Gestión de períodos y nóminas

Controla el ciclo completo de cada período de nómina con validación automática.

Capacidades clave:

Creación automática de períodos de nómina.
Cálculo y recálculo de nóminas.
Validación de datos y detección de inconsistencias.
Sincronización con software contable.
Descarga de archivos para pago bancario.
Manejo de novedades (horas extras, descuentos, bonificaciones, licencias, incapacidades, etc.).
Nóminas electrónicas con estados de transmisión a DIAN.

Pagos y facturación

Gestiona la suscripción a Aleluya, generación de facturas y registro de pagos.

Capacidades clave:

Cálculo automático del valor de suscripción según plan.
Generación de facturas electrónicas.
Registro de pagos (PSE, débito automático, tarjeta de crédito/débito).
Gestión de ciclos de facturación (mensual, anual).
Soporte para partners.

Funcionalidades complementarias

Capacidades clave:

Gestión de usuarios y permisos por rol.
Gestión de novedades y reclamaciones.
Descargas de archivos especiales y reportes.
Validación de documentos.
Consultas a proveedores externos (información exógena, validaciones).

¿Cómo integrar?

Aleluya API ofrece un conjunto completo de endpoints REST para construir soluciones personalizadas.

APIs REST

Nuestras APIs REST son la base del ecosistema de Aleluya, potenciando todas las funcionalidades principales.

Características:

Endpoints organizados por recurso (companies, workers, payrolls, periods, etc.).
Autenticación por OAuth 2.0 y cookies.
Manejo granular de permisos y roles.
Documentación completa con ejemplos.
Límite de 90 peticiones por minuto por IP y por usuario.

Casos de uso:

Integración de nómina en plataformas de RR. HH. existentes.
Dashboards de reportes personalizados.
Sincronización bidireccional con sistemas contables.
Automatización de procesos de soporte.

Ambientes disponibles

Producción

URL: https://nominapp-api.herokuapp.com

Cuándo usarlo:

Tu integración está lista y probada.
Vas a procesar nóminas reales.
Necesitas transmitir información a DIAN, PILA, EPS, etc.
Realizarás pagos de seguridad social reales.
Trabajarás con datos de personas reales.

Consideraciones:

⚠️ Las transacciones son irreversibles.
⚠️ Los archivos transmitidos a DIAN son oficiales.
⚠️ Los pagos de seguridad social son reales.
⚠️ Requiere credenciales de producción.

Staging (Sandbox)

URL: https://nominapp-api-stage.herokuapp.com

Cuándo usarlo:

Estás desarrollando y probando tu integración.
Quieres validar flujos sin afectar datos reales.
Necesitas probar escenarios de error.
Estás aprendiendo cómo funciona la API.
Pruebas de calidad antes de ir a producción.

Características:

✅ Datos de prueba separados de producción.
✅ No transmite a DIAN ni entidades reales.
✅ Permite probar errores y validaciones.
✅ Mismo comportamiento que producción.

🚧
Usa el ambiente de staging para probar tu integración sin afectar datos reales.

Consideraciones técnicas

Límites y restricciones

Rate limit: 90 peticiones por minuto (ventana móvil de 60 segundos).
Tamaño de archivos adjuntos: Máximo 1MB por archivo.
Respuestas: Formato JSON.
Períodos: Soporte para nómina mensual y quincenal.

Contexto normativo colombiano

Aleluya cumple con regulaciones locales clave:

DIAN: Transmisión de nómina electrónica y certificados.
UGPP: Gestión de archivos especiales.
EPS/ARL/AFP/CCF: Afiliación y pago automático.
PILA: Pago centralizado de aportes.

Prácticas recomendadas para el éxito

Planificación de tu implementación

Define tus necesidades: Identifica qué módulos de Aleluya requiere tu solución.
Mapea tus datos existentes: Revisa qué información ya recopilas de tus clientes.
Diseña el flujo de usuarios: Planifica cómo guiarás a tus usuarios a través de Aleluya.
Prueba en sandbox: Válida tu integración antes de llevarla a producción.
Considera el rate limit: Diseña tu arquitectura para respetar 90 req/min.

Preparación para el lanzamiento

✅ Prueba exhaustivamente en el entorno staging.
✅ Documenta tus puntos de integración.
✅ Define procesos de soporte y resolución.
✅ Crea runbooks para troubleshooting.
✅ Planifica actualizaciones y mantenimiento.

Enfoque en experiencia del usuario

Diseña flujos intuitivos y claros.
Proporciona mensajes de error descriptivos.
Incluye documentación de ayuda integrada.
Maneja errores de rate limit elegantemente (retry con backoff exponencial).
Válida los datos antes de enviar a Aleluya para reducir rechazos.

Mantenimiento y mejora continua

📊 Monitorea el rendimiento y errores (429, timeouts).
💬 Recopila feedback de usuarios.
🔄 Planifica actualizaciones regularmente.
📰 Mantente al día con cambios en la plataforma.
📝 Revisa logs y errores regularmente.

¿Listo para comenzar?

Después de familiarizarte con las capacidades de la plataforma, tu siguiente paso será:

Regístrate para una cuenta de desarrollador para acceder a los ambientes.
Lee la documentación de API Endpoints para guías técnicas detalladas.
Explora la referencia completa de recursos disponibles.
Prueba con datos de ejemplo en staging.

Para soporte durante la integración, accede a nuestro Centro de Ayuda o contacta al equipo de soporte.