Guatemala Payroll - Planilla GT

Full Guatemalan payroll on Odoo 17: IGSS, ISR mensual, Bono 14, Aguinaldo, Vacaciones, Indemnizacion, IRTRA, INTECAP, Bonificacion Incentivo, horas extras 50%/100%, employee advances, shift scheduling vs attendance with approval flow.

ARMKU LLC  ·  Odoo 17.0  ·  version 17.0.7.5.0  ·  OPL-1

A complete Guatemalan payroll layer for Odoo 17 — every salary rule, accrual, withholding, and quincenal workflow a real GT business needs to run payroll without spreadsheets.

Compatibility

• Odoo 17.0 Community / Enterprise (tested in production on a multi-location restaurant)

• Requires om_hr_payroll and om_hr_payroll_account from the Odoo Mates community apps — install separately (free, MIT)

What it adds (the headline features)

1. IGSS afiliación on the employee record

Two new fields on hr.employee: gt_igss_afiliado (Bool) and gt_igss_fecha_inicio (Date). The IGSS employee salary rule only applies when both conditions hold AND the payroll period starts on or after the affiliation date. This lets HR hire someone today and start the IGSS clock only when they actually affiliate — exactly how Guatemalan labour law expects (you have until month 4).

2. Employee cash advances (Adelantos)

A new l10n_gt.payroll.adelanto model: employee requests an advance, admin approves it, cash or bank pays it out, and the next payroll auto-deducts it via the ADELANTO_DEDUC salary rule until the balance reaches zero. Per-payslip view shows outstanding advances per employee.

3. Shift scheduling (Turnos)

• l10n_gt.payroll.turno — your shift catalogue (Cocina mañana, Sala tarde, Cierre, etc.).

• l10n_gt.payroll.programacion — assignments per employee per day.

• Weekly target: 42h (the Guatemalan legal cap).

4. Scheduled vs actual variance approval

Daily cron walks through hr.attendance and compares to l10n_gt.payroll.programacion. Every diff (tardy, early leave, OT, no-show, swap) becomes a l10n_gt.payroll.variacion record that the admin approves or rejects before it affects payroll. Full audit trail on every state change.

5. Salary rules — the full Guatemalan stack

All loaded via data XML on install. Restructure or override via the standard Odoo salary rule editor.

6. Liquidación wizard

One screen: select employee + termination date → wizard pre-fills final salary, prorrata Bono 14 / Aguinaldo / Vacaciones, indemnización, final IGSS, final ISR. Creates the final payslip in one click.

7. Boleta de pago employee portal

Employees see their own payslips at /my/boleta. Sign-with-DPI flow: a tokenised URL emails them the link, they sign (touchscreen or mouse), the IP + timestamp are stored, and the signed PDF replaces the unsigned version.

8. Guatemalan holidays 2026

Pre-loaded into resource.calendar.leaves so payroll doesn't have to enter Independence Day, Holy Week, etc. by hand.

New models added

Payroll inputs auto-generated

compute_sheet() is overridden to populate hr.payslip.input with:

Install

# 1) Install om_hr_payroll + om_hr_payroll_account first
git clone https://github.com/odoomates/odooapps.git /tmp/odoomates
cp -r /tmp/odoomates/om_hr_payroll /tmp/odoomates/om_hr_payroll_account YOUR_ADDONS_DIR/

# 2) Drop this module into YOUR_ADDONS_DIR
unzip l10n_gt_payroll-17.0.7.4.0.zip -d YOUR_ADDONS_DIR/

# 3) Install
sudo systemctl stop odoo
sudo -u odoo /path/to/odoo-bin \
  -c /etc/odoo/odoo.conf -d YOUR_DB \
  --stop-after-init --no-http \
  -i l10n_gt_payroll
sudo systemctl start odoo

Initial setup (one-time, ~30 min)

After install:

1. HR → Configuración → Settings — set your company's IGSS patrono number.

2. HR → Employees — for each existing employee, set IGSS afiliado + fecha inicio.

3. Payroll → Configuración → Estructuras Salariales — confirm the GT structure loaded (KS-GT-NOM).

4. Payroll → Configuración → Turnos — define your shift catalogue.

5. Payroll → Programación — schedule the first week.

6. Wait for the daily variance cron to run (or trigger it manually from System Parameters → Scheduled Actions).

Best-fit use cases

• Restaurants and food-service businesses in Guatemala (5–200 employees).

• Distributors / wholesalers running quincenal payroll.

• Service businesses needing IGSS/ISR compliance plus shift scheduling.

Not for fully-remote companies with no shift component, or businesses outside Guatemala. The salary rules are GT-specific.

Limitations / honest caveats

• This module is Odoo 17 only until the 18 port lands.

• ISR mensual table reflects the SAT scale at module write time; review when SAT publishes new scales (one-line update to data/salary_rules.xml).

• IGSS rates are hard-coded — if the IGSS board changes them, override via the salary rule editor.

• The Bono 14 / Aguinaldo accrual uses a simplified pro-rata; if you need the SAT-exact monthly accrual, override the rule.

• The COA mapping in post_init.py falls back to 2.1.01.01 Cuentas por Pagar if a dedicated 2.1.05.01 Sueldos por Pagar account isn't found. Create the dedicated account in your COA to split payroll from general AP.

Support

This module is a 4,500-line localization layer — we strongly recommend the Installation & Setup Service for first-time installs to make sure your salary rules, sequence, IGSS settings, and mail templates wire correctly.

Support. Bugs and configuration questions are answered by the author. Write to rkong@armku.us quoting your order number.

© 2026 ARMKU LLC  ·  armku.us