Odoo Module Development – Spanish Payroll System ("Nomina")

# Odoo Module Development – Spanish Payroll System ("Nomina") ## Project Overview I am looking for an experienced Odoo developer to build a custom **Odoo Community** module called **Monina**, a Spanish payroll engine designed for small businesses, autónomos with employees, and accounting/payroll firms (asesorías) managing payroll for multiple client companies. The module calculates employee payroll, employer costs, Social Security contributions and IRPF withholdings **in full compliance with Spanish regulations**, generates payslip PDFs, and posts accounting entries. It must be delivered as a standalone, installable, **open-source** module that I can clone from a Git repository and drop into my `addons/` folder. This is a compliance-critical module. Incorrect payroll calculations create legal problems with employees and the Tax Agency. Read the **Compliance Requirements** section carefully — generic or simplified calculations will not be accepted. --- ## CRITICAL CONSTRAINTS (non-negotiable — read first) ### 1. Odoo Version: **Odoo 17 Community Edition** My entire stack runs on **Odoo 17 CE** with OCA Spanish localization modules (`l10n_es`, `l10n_es_aeat`, `l10n_es_aeat_mod111`, `mod190`, etc.). The module **must target Odoo 17 CE** and be compatible with these OCA modules. Do NOT propose Odoo 18/19 unless you also commit to guaranteed 17 compatibility. ### 2. IRPF must follow the **official AEAT algorithm** IRPF withholding is **NOT a fixed percentage or a simple formula.** It must implement the official withholding procedure defined in the IRPF Regulation (Reglamento del IRPF, RD 439/2007, art. 80 y ss.) and the annual AEAT "algoritmo de cálculo de retenciones". The calculation must account for: * Personal and family situation (marital status, children/descendants, ascendants) * Disability of the worker or dependents * Contract type and duration * Number of payments (12 / 14) * Geographic considerations (e.g. Ceuta/Melilla) where applicable * Mid-year regularization when circumstances change A flat-rate or "~15%" approximation will be rejected. ### 3. All legal rates and tables must be **configurable parameters**, NOT hardcoded Social Security rates, contribution bases (min/max), SMI, MEI, FOGASA, professional training, unemployment, and IRPF brackets/tables **change every year**. They must live in **editable configuration models/tables inside Odoo** (admin-editable UI), so I can update them annually myself without touching code. Hardcoding any of these values in Python is not acceptable. ### 4. Multi-company aware My architecture is multi-company (one Odoo, one company per client). Every payroll record, employee, contract, and accounting entry must respect `company_id` and be **fully isolated per company**. Data must never leak between companies. ### 5. Open-source license & ownership Delivered under **LGPL-3** (same as Odoo/OCA modules). Full copyright and intellectual property of the commissioned code transfer to me. No proprietary lock-in, no license fees, no call-home. ### 6. Maintainable, well-documented, modular code The code must be written to be easily understood and extended later by other developers (or AI tools). This means: clear modular architecture (separation of concerns — calculation logic, data models, reports, config all cleanly separated), meaningful inline comments on all calculation logic (especially the IRPF and SS methods), descriptive naming, and docstrings on public methods. Priority is maintainability and readability over cleverness. The goal is that I or any future developer can pick up the module, understand it, and improve it without the original author. --- ## Reference figures (2026 — for validation, must be configurable) These are the current values; the module must store them as editable parameters, not constants. Use them to validate your sample calculations: * Contingencias comunes: 28,30% total (23,60% employer / 4,70% employee) * Desempleo (indefinido): 7,05% (5,50% employer / 1,55% employee) * MEI: 0,90% (0,75% employer / 0,15% employee) * FOGASA: 0,20% (employer) * Formación profesional: 0,70% (0,60% employer / 0,10% employee) * SMI 2026 and max/min contribution bases: configurable * Typical total employer cost ≈ gross + ~31% **Validation scenario** (the module must reproduce this, ±small rounding): Gross 2.500 €/month, indefinite contract, single, no children, 14 payments: * Net employee ≈ 1.989 €/month * Total employer cost ≈ 3.275 €/month (~+31% over gross) Provide your computed breakdown for this exact case in your proposal. --- ## Functional Requirements ### Employee & Contract Management Extend Odoo HR (`hr.employee`, `hr.contract`) to support: * Employee personal & family data relevant to IRPF (marital status, children, ascendants/descendants, disability, year of birth) * Contract type: permanent (indefinido) / fixed-term (temporal) * Gross annual salary, monthly salary, number of payments (12/14) * Extra payments: prorrateadas vs no prorrateadas (must affect monthly calc) * Working hours, full/part-time, start/end dates, employment status ### Payroll Calculation Engine Compute, per employee per period: * Gross salary * Employee Social Security contributions (itemized by concept) * IRPF withholding (per official AEAT algorithm, §2 above) * Net salary * Employer Social Security contributions (itemized by concept) * Total employer cost Show a clear breakdown of every contribution concept and its rate. ### Payroll Records & Workflow Monthly payroll records with statuses: Draft → Reviewed → Approved → Paid. ### Payslip PDF Professional Spanish payslip (nómina) PDF generated from Odoo, containing employee info, employer info, period, earnings (devengos), deductions (deducciones), bases de cotización, net pay, and an employer-cost summary. Layout should resemble the standard official payslip structure. ### Accounting Integration Auto-create accounting entries for approved payrolls, respecting the Spanish PGC chart of accounts (e.g. 640 sueldos y salarios, 642 SS a cargo de empresa, 476 Organismos SS acreedores, 4751 HP acreedora por retenciones). Must work with the installed Spanish localization (`l10n_es`). ### Tax model feed (111 / 190) Output the IRPF withholding data so it can feed (or be reconciled with) the existing OCA AEAT models **111** (quarterly) and **190** (annual). Compatibility with these OCA modules is required — at minimum a clean export/aggregation of withholdings. ### Employer Cost Simulator Standalone simulator: input gross annual or monthly + contract type → estimate net employee salary, employer SS and total employer cost. (I intend to expose this as a lead-generation tool, so a clean callable method/endpoint is a plus.) ### Dashboard Totals: employees, total payroll cost, total SS, total IRPF, total net salaries — filterable by company and period. --- ## Scope — Version 1 EXCLUDES (future phases) * SILTRA / Sistema RED / Contrat@ / Certific@2 integration * Automatic government submissions * Employee self-service portal * Time tracking, vacation, sick-leave management * Automatic collective-agreement (convenios) database These are explicitly out of scope for V1. --- ## Deliverables * Complete source code in a **Git repo (GitHub/GitLab)**, LGPL-3. * Module installable by copying into `addons/` + Update Apps List, **no errors**. * Installation guide, configuration guide (esp. how to edit yearly rate tables), user guide, technical documentation. * Sample demo data + the validation scenario above implemented as a test. * **Automated tests** covering: SS calculation, IRPF per AEAT algorithm, net/cost totals, multi-company isolation, and the reference 2.500 € case. ## Acceptance Criteria The module must install cleanly on Odoo 17 CE, create payroll records, calculate SS and IRPF correctly (validated against the reference scenario and AEAT method), generate the payslip PDF, post correct PGC accounting entries, respect multi-company isolation, keep all legal rates editable in the UI, and pass the included tests. --- ## How to Apply (please include) * Odoo modules you've built (links), GitHub profile. * **Confirm Odoo 17 CE** support and OCA `l10n_es` compatibility. * Your computed breakdown for the **2.500 €/month reference scenario**. * How you will implement the **official AEAT IRPF algorithm** (brief approach). * How you will keep legal rates **configurable** (data model approach). * Proposed architecture, estimated timeline, Spanish payroll experience. Applicants who address IRPF compliance and yearly-rate configurability in their proposal will be prioritized. Generic payroll-template answers will be ignored.