Преминете към съдържание

Installation Guide

Bulgarian Localization for Odoo 18 — 50+ modules, 5 repositories, full cycle of Bulgarian accounting

VAT Payroll Banking Customs NRA Intrastat

What does the localization include?

The Bulgarian localization for Odoo 18 is a set of 50+ modules organized into functional groups. It covers the full cycle of Bulgarian accounting — from chart of accounts and VAT declarations to payroll, customs operations, and banking integration.

Modules are in 5 repositories

RepoLicenseModulesDescription
l10n-bulgariaLGPL-326Community Edition — core
l10n-bulgaria-eeOPL-118Enterprise Edition — payroll, assets, banking
l10n-bulgaria-enterpriseOPL-12Enterprise specialized — VAT, customs
l10n-bulgaria-expertOPL-15Expert — tax administration, InfoPay
l10n-bulgaria-ocaLGPL-329OCA compatible variants

Table of Contents

Group "Core" — mandatory base

Command: install core

ModuleDescription
l10n_bg_configCentral configuration, mixin architecture, UIC validation, encryption
l10n_bg_cityEKATTE database — 28 regions, 265 municipalities, 5000+ settlements
l10n_bg_address_extendedExtended addressing per Bulgarian standard
l10n_bg_tax_officesNRA offices and territorial directorates
l10n_bg_company_registryIntegration with the Commercial Register (API)
partner_multilangMultilingual names with Cyrillic transliteration
l10n_bg_multilangMultilingual support for partners, companies, employees
markdown_viewer_localeLocalized documentation viewer
Dependencies

base, account, contacts, hr, stock

What it does
  • Creates the Bulgarian chart of accounts
  • Configures taxes (20%, 9%, 0% — sales and purchases)
  • Creates fiscal positions (Domestic, EU B2C, EU B2B, Outside EU)
  • Loads the geographic database of Bulgaria
  • Activates multilingual support (BG/EN)
After installation:
  1. Go to Settings → Accounting → Company Configuration
  2. Fill in UIC/BULSTAT, VAT number, address
  3. Check the chart of accounts in Accounting → Configuration → Accounts

Group "Bank" — banking integration and payments

Command: install bank

ModuleDescription
l10n_bg_bank_walletEncrypted key wallet (PBKDF2+Fernet)
l10n_bg_infopayInfoPay API — statement and payment synchronization
Encrypted Wallet

Creates an encrypted wallet for each user — API keys, RSA keys, certificates

InfoPay Synchronization

Bank statements, single and batch payments (BGN/EUR)

IBAN Identification

Automatic identification of bank accounts by IBAN

Dependencies: account, base, web

After installation:
  1. Grant permissions: User → Groups → "Crypto Wallet: Administrator"
  2. The "Crypto Wallets" menu appears in the main menu
  3. For InfoPay: Settings → Company → InfoPay Unique ID + Access Token
  4. Bank journals → fill in "InfoPay Account ID"

Additional modules (EE)

l10n_bg_infopay_online

Extended UI with batch payments Expert, 15 EUR

l10n_bg_account_bank_statement_import_mt940

MT940 import EE

l10n_bg_account_statement_import_mt940

MT940 import CE

Group "VAT" — tax administration and reporting

Command: install vat

ModuleDescription
l10n_bg_reports_auditSQL engine for audit, 14 models, account tags
l10n_bg_reports_configConfiguration views for reports
l10n_bg_vat_reportsVAT declaration, sales/purchase journals, VIES EE, 250 EUR
l10n_bg_report_vatExtended VAT reports with CSV/ZIP/PDF export for NRA Enterprise, 250 EUR
l10n_bg_tax_adminProtocols per Art. 117, customs declarations, TAMs Expert, 300 EUR
l10n_bg_config_plugins_art_69_2Art. 69(2) VAT Act — place of supply in another EU member state
l10n_bg_config_plugins_art_82_2Art. 82(2) VAT Act — reverse charge for services from EU

Dependencies: account, stock, purchase_stock, sale

reports_audit

  • SQL views for purchase journal, sales journal, VIES
  • Account tags for VAT declaration cells (+11, +12_1, +12_2, +13, +21, +22, +31, +41, +42...)
tax_admin
  • Protocols per Art. 117 VAT Act (automatic for ICA, services from EU)
  • Customs declarations (SAD, MRN, tariff rates)
  • Tax Action Maps — the "brain" of the system
  • Two new tax types: customs_rate and private_rate
  • Private use with coefficient

config_plugins_art_82_2

  • Fiscal position "0% Art. 82(2)" for EU services
  • Group tax with reverse charge (receivable + payable via account 430)
  • Mapping: 20%/9%/0% → 0% PTC Art. 82(2)
After installation:
  1. Check fiscal positions: Accounting → Configuration → Fiscal Positions — Domestic (seq=10), EU B2C (20), EU B2B (30), Outside EU (40), 0% Art. 69(2) (seq=60), 0% Art. 82(2) (seq=61)
  2. Configure Tax Action Maps (if you have tax_admin) — Domestic: 4 TAMs, EU B2B: 4 TAMs, Outside EU: 4 TAMs, Art. 82(2): 2 TAMs
  3. Check tax tags: Receivable Art.82(2): base +12_2, tax +22 / Payable Art.82(2): base +31, tax +41 / Receivable ICA: base +12_1, tax +22 / Payable ICA: base +31, tax +41
  4. Apply the templates (if art_69_2/art_82_2 are installed): Settings → Accounting → Apply Chart Template

Operation types (quick reference)

OperationVAT Act Art.DocumentType of VATDoc Type
ICA13, 62, 84, 117Protocol117_protocol_8409
Services from EU21, 82, 117Protocol117_protocol_82_209
Import57Customs decl.in_customs07
Private use9(3), 117Protocol117_protocol_6_309
Triangular15, 117Protocol117_protocol_1509
ICS7, 28Invoice 0%standard01
Export28Invoice 0%out_customs07

Group "Payroll" — payroll and HR

Command: install payroll

ModuleDescription
l10n_bg_payroll_classificationsNKPD positions and KID activities with MOD rates
l10n_bg_hr_holidays61 leave types per Labour Code (17 NHIF, 4 annual, 8 civil, 7 maternity...)
l10n_bg_hr_payrollPayroll with SSI/HI/SPF/OAWI calculations EE, 250 EUR
l10n_bg_hr_payroll_accountPayroll → accounting EE
l10n_bg_hr_contract_signElectronic signing of employment contracts EE, 150 EUR
l10n_bg_config_plugins_payrollAccounts for SSI, NHIF, ASPF, GFLA EE, 20 EUR
l10n_bg_config_plugins_nsi_expencesExpense accounts per NSI — 601.x, 602.x series EE, 15 EUR

Dependencies: hr, hr_payroll, hr_contract, hr_holidays

Full Salary Structure

Automatic calculation of social security contributions per Bulgarian legislation

NKPD Classifier

7800+ positions, KID classifier with minimum insurable income (MOD)

61 Leave Types

Per the Labour Code + Electronic signing of employment contracts

After installation:
  1. Configure NKPD positions: HR → Configuration → NKPD
  2. Set MOD for each KID activity
  3. Create salary structures for different contract types
  4. If needed — apply payroll and NSI plugins from Settings

Group "Reports" — themes and documents

Command: install reports

ModuleDescription
l10n_bg_report_themeSection theme (Header/Article/Footer), SF fonts, logo colors
l10n_bg_sign_report_themeUser signatures in QWeb templates EE, 25 EUR
l10n_bg_invoice_copyWatermark "COPY" on invoices
l10n_bg_report_stockAcceptance-delivery protocols for warehouse
l10n_bg_sale_order_delivery_noteGoods receipt for sales
l10n_bg_reports_audit_assetsDepreciation reports EE
l10n_bg_assetsTax depreciation per Bulgarian standards EE, 150 EUR

Dependencies: web, sale, account, stock, purchase

After installation:
  1. Settings → Report Theme → choose logo, colors, font
  2. Configure sections: Header, Article, Footer
  3. For invoices — check the template in Accounting → Configuration → Reports

Group "Trade" — tariffs, customs, Intrastat

Command: install trade

ModuleDescription
l10n_bg_tariff_codeTARIC/HS/CN codes with EU API integration
taric_ai_classifierAI classification of goods via Claude AI
l10n_bg_intrastatIntrastat XML declarations — arrivals/dispatches EE, 150 EUR
l10n_bg_customs_currency_rate_liveExchange rates from Customs Agency Enterprise
l10n_bg_customs_rateCustoms rate button on invoices EE

Dependencies: account, stock, stock_delivery, account_intrastat

After installation:
  1. Products → fill in TARIC/CN codes
  2. For AI classification — configure Claude API key in Settings
  3. For Intrastat — set thresholds and responsible person

Group "NRA" — API integration

Command: install nra

ModuleDescription
l10n_bg_api_nraREST API to NRA — declarations D1, D6, ETZ, VAT, VIES
l10n_bg_bank_walletWallet for API keys (dependency)

Dependencies: base, l10n_bg_config, l10n_bg_bank_wallet

OAuth 2.0

Authentication with NRA

Declarations

Form 1, Form 6, ETZ

VAT and VIES

VAT declarations and VIES

Validation

Rate limiting and XML validation

After installation:
  1. Settings → Company → NRA configuration
  2. Enter API key from portal.nra.bg
  3. Store the key in Crypto Wallet

Group "POS" — fiscal printer

Command: install pos

ModuleDescription
l10n_bg_erp_net_fpErpNet.FP integration for fiscal printers

Dependencies: point_of_sale, account, bus, mail

After installation:
  1. POS → Configuration → Fiscal Printers → Add
  2. Enter the printer's IP address and port
  3. Test the connection

Group "Multilingual"

Command: install multilingual

partner_multilang

Automatic transliteration Cyrillic ↔ Latin

l10n_bg_multilang

Multilingual partners, companies, employees

l10n_bg_mrp_multilang

Multilingual work centers in MRP

l10n_bg_project_multilang

Multilingual tasks in Project

Full Installation Step by Step

Command: install all

Important: The Core must be installed FIRST. The remaining groups can be installed in any order.
1
Core

Base, chart of accounts, taxes, fiscal positions

2
Bank

Wallet and InfoPay

3
VAT

Reports, protocols, TAMs

4
Payroll

Payroll, leaves, NKPD

5
Reports

Themes, documents, assets

6
Trade

Tariffs, customs, Intrastat

7
NRA

API integration

8
POS

Fiscal printer

Reference Configuration (Raytron)

Tax Structure — Sales

TaxSeqBase TagTax AccountTax Tag
20% VAT101+11453200+21
9% VAT111+13453200+24
0% Export121+14——
0% ICS122+15——
0% Exempt125+19——
0% Art. 69(2)501+23——

Tax Structure — Purchases

TaxSeqBase TagTax AccountTax Tag
20% FTC201+31453100+41
20% PTC202+32453100+42
20% OTC203+30453100+30
9% FTC/OTC211-212Analogous structure with 9% rate

Reverse Charge (Group taxes via 430)

20% EU PTC (ICA)

Receivable: base +12_1, tax -100% 453200 +22, +100% 430

Payable: base +31, tax +100% 453100 +41, -100% 430

0% PTC Art. 82(2)

Receivable: base +12_2, tax -100% 453200 +22, +100% 430

Payable: base +31, tax +100% 453100 +41, -100% 430

Tax Action Maps (by fiscal position)

Domestic
move_typebg_move_typetype_vatdoc
out_invoicestandardstandard01
out_refundstandardstandard01
in_invoicestandardstandard01
in_refundstandardstandard01
EU B2B
move_typebg_move_typetype_vatdoc
out_invoicestandardstandard01
out_refundstandardstandard01
in_invoiceprotocol117_protocol_8409
in_refundprotocol117_protocol_8409
Outside EU
move_typebg_move_typetype_vatdoc
out_invoicestandardout_customs01
out_refundstandardout_customs01
in_invoicecustomsin_customs07
in_refundcustomsin_customs07
Art. 82(2)
move_typebg_move_typetype_vatdoc
in_invoiceprotocol117_protocol_82_209
in_refundprotocol117_protocol_82_209

Connection and Management Methods

1. Odoo Connection Manager (GUI)

Graphical application for managing connections to Odoo instances.

Launch: python3 odoo_connect.py

  • Save multiple Odoo connections (URL, database, user, API key)
  • Test connection via XML-RPC
  • Create SSH aliases in ~/.ssh/config
  • Load, edit, and delete saved connections

Configuration: .odoo_connections/connections.json and ~/.ssh/config

2. XML-RPC (programmatic access)

Direct access to Odoo via XML-RPC for automation.

Authentication:

import xmlrpc.client
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, user, api_key, {})
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')

Typical operations: Install/upgrade modules, read/write taxes, fiscal positions, repartition lines, create Tax Action Maps

3. SSH server access

Basic commands:

# Login
ssh terraros-commerce

# Command in Docker container
ssh server "docker exec -u 0 odoo "

# Pull repo
ssh server "cd /opt/odoo/rv/l10n-bulgaria && git pull origin 18.0"

# Restart Odoo
ssh server "docker restart odoo"

# Symlink for new module
ssh server "docker exec -u 0 odoo sh -c \
  'cd addons/18.0 && ln -sf /opt/odoo/rv// .'"

# Logs
ssh server "docker logs odoo --tail 100"
4. Full deployment cycle
  1. Development (local)
    Code change → git commit → git push origin 18.0
  2. Pull on server
    ssh server "cd /opt/odoo/rv/ && git pull origin 18.0"
  3. Symlinks (if new module)
    docker exec -u 0 odoo sh -c 'cd addons/18.0 && ln -sf ...'
  4. Restart / Upgrade
    docker restart odoo or docker exec odoo odoo -u -d --stop-after-init
  5. Verification
    XML-RPC test, check taxes, fiscal positions, TAMs

Saved Instances

NameURLType
octa-lightportal4.octa-light.comProduction
demo-18demo-18.odoo-shell.spaceDemo/Test
alpinter-bulgariaworld-of-tents.odoo.accomodata.netProduction
miv-electronicserp.mivelectronics.comProduction
terraros-commercewww.odoo-shell.devProduction + SSH

Claude Code — trained assistant for Bulgarian localization

Claude Code (Opus 4.6) is trained and configured to work as a full-featured assistant for installation, configuration, and maintenance of the Bulgarian localization for Odoo 18.

Source Code Knowledge
  • Full analysis of Odoo 18 module lifecycle
  • Dependency graph, state machine, loading sequence
  • ir.module.module, ir.model.data, _module_data_uninstall()
  • Migration scripts (pre/post/end), hooks (pre_init/post_init/uninstall)
Localization Knowledge
  • Architecture of 54+ modules in 5 repositories
  • Detailed analysis of l10n_bg_tax_admin
  • SQL engine of l10n_bg_reports_audit
  • VAT reports — declarations, journals, VIES, NRA formats
  • Reference tax configuration from Raytron
Practical Skills
  • XML-RPC connection (GUI + programmatic)
  • Remote module installation and upgrade
  • Tax configuration check and correction
  • Creating Tax Action Maps, fiscal positions
  • SSH access, Docker, symlink management
  • Git operations — commit, push, pull
  • Finding and fixing bugs

Memory

  • User profile (Rosen, Bulgarian Odoo 18 developer)
  • All repository paths (local and server)
  • Live instance configuration (Raytron, Octa Light, Demo-18, Alpinter, Terraros)
  • Base installation of VM+Docker+Cloudflare server
  • Groups for quick module installation
  • CLAUDE.md instructions, memory files, auto memory

How to Provide the Training

For Claude Code to work fully with the Bulgarian localization on a new machine or in a new project, the following must be provided:

1. CLAUDE.md — project instructions

Language, memory, brief on start
/home/rosen/.../claude.ai/CLAUDE.md

2. Memory files — accumulated knowledge
  • user_profile.md — user profile
  • project_l10n_bg_overview.md — architecture of 54+ modules
  • reference_repo_paths.md — repository paths
  • odoo18_module_lifecycle.md — module installation
  • installation_guide_bg.md — this guide
  • server_base_install_vm_docker.md — server installation
  • module_l10n_bg_tax_admin.md — tax_admin analysis
  • module_l10n_bg_reports_audit.md — reports_audit analysis
  • module_l10n_bg_vat_reports.md — VAT reports analysis
  • raytron_fiscal_config.md — reference configuration
  • raytron_tax_config_detailed.md — detailed tax templates
3. Odoo Connection Manager
  • odoo_connect.py — GUI for connection management
  • .odoo_connections/connections.json — saved instances
4. Access
  • XML-RPC API keys for Odoo instances
  • SSH configuration (~/.ssh/config) for servers
  • GitHub SSH keys for push/pull

What is NOT trained (limitations)

  • Cannot access the Odoo web interface (no browser)
  • Cannot apply Chart of Accounts templates — this is done from the GUI
  • Cannot test invoices end-to-end (configuration only)
  • Cannot generate PDF reports
  • Not trained for Odoo.sh specific deployment

Example Commands for Claude Code

"install vat in terraros-commerce"
"check taxes in octa-light"
"fix Art. 82(2) per the reference"
"pull l10n-bulgaria on the server"
"create symlink for l10n_bg_infopay"
"launch the configurator"
"show what is installed in demo-18"

Frequently Asked Questions

Core first, then as needed. Odoo automatically resolves dependencies.

Modules marked with (EE) require Enterprise. Community modules work with CE.

Compare with the Raytron reference — tags, accounts, repartition lines.

Templates are applied from Settings → Apply Chart Template. Or configure manually.

ssh server "cd /opt/odoo/rv/l10n-bulgaria && git pull origin 18.0"
docker restart odoo

docker exec -u 0 odoo sh -c 'cd /var/lib/odoo/.local/share/Odoo/addons/18.0 && \
  ln -sf /opt/odoo/rv// .'
docker restart odoo

Technical Support

In case of problems:
  1. Check logs: docker logs odoo --tail 100
  2. Debug Mode: Settings → Activate Developer Mode
  3. Test XML-RPC: python3 odoo_connect.py
  4. Check symlinks: docker exec -u 0 odoo ls -la /var/lib/odoo/.local/share/Odoo/addons/18.0/

Version: 2.0 | Date: 24.03.2026 | Compliance: VAT Act, Labour Code, Social Insurance Code effective from 01.01.2026

Installation and configuration guide for Bulgarian localization for Odoo 18 — 50+ modules, 5 repositories, 9 installation groups