Bulgarian Localization for Odoo 18: Installation Guide

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

Repo	License	Modules	Description
l10n-bulgaria	LGPL-3	26	Community Edition — core
l10n-bulgaria-ee	OPL-1	18	Enterprise Edition — payroll, assets, banking
l10n-bulgaria-enterprise	OPL-1	2	Enterprise specialized — VAT, customs
l10n-bulgaria-expert	OPL-1	5	Expert — tax administration, InfoPay
l10n-bulgaria-oca	LGPL-3	29	OCA compatible variants

Table of Contents

• Group "Core"
• Group "Bank"
• Group "VAT"
• Group "Payroll"
• Group "Reports"
• Group "Trade"
• Group "NRA"
• Group "POS"
• Group "Multilingual"

• Full Installation

  • Reference Configuration
• Tax Action Maps
• Connection and Management
• Claude Code Assistant
• Frequently Asked Questions

Group "Core" — mandatory base

Command: install core

Module	Description
l10n_bg_config	Central configuration, mixin architecture, UIC validation, encryption
l10n_bg_city	EKATTE database — 28 regions, 265 municipalities, 5000+ settlements
l10n_bg_address_extended	Extended addressing per Bulgarian standard
l10n_bg_tax_offices	NRA offices and territorial directorates
l10n_bg_company_registry	Integration with the Commercial Register (API)
partner_multilang	Multilingual names with Cyrillic transliteration
l10n_bg_multilang	Multilingual support for partners, companies, employees
markdown_viewer_locale	Localized 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

Module	Description
l10n_bg_bank_wallet	Encrypted key wallet (PBKDF2+Fernet)
l10n_bg_infopay	InfoPay 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

Module	Description
l10n_bg_reports_audit	SQL engine for audit, 14 models, account tags
l10n_bg_reports_config	Configuration views for reports
l10n_bg_vat_reports	VAT declaration, sales/purchase journals, VIES EE, 250 EUR
l10n_bg_report_vat	Extended VAT reports with CSV/ZIP/PDF export for NRA Enterprise, 250 EUR
l10n_bg_tax_admin	Protocols per Art. 117, customs declarations, TAMs Expert, 300 EUR
l10n_bg_config_plugins_art_69_2	Art. 69(2) VAT Act — place of supply in another EU member state
l10n_bg_config_plugins_art_82_2	Art. 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)

Operation	VAT Act Art.	Document	Type of VAT	Doc Type
ICA	13, 62, 84, 117	Protocol	117_protocol_84	09
Services from EU	21, 82, 117	Protocol	117_protocol_82_2	09
Import	57	Customs decl.	in_customs	07
Private use	9(3), 117	Protocol	117_protocol_6_3	09
Triangular	15, 117	Protocol	117_protocol_15	09
ICS	7, 28	Invoice 0%	standard	01
Export	28	Invoice 0%	out_customs	07

Group "Payroll" — payroll and HR

Command: install payroll

Module	Description
l10n_bg_payroll_classifications	NKPD positions and KID activities with MOD rates
l10n_bg_hr_holidays	61 leave types per Labour Code (17 NHIF, 4 annual, 8 civil, 7 maternity...)
l10n_bg_hr_payroll	Payroll with SSI/HI/SPF/OAWI calculations EE, 250 EUR
l10n_bg_hr_payroll_account	Payroll → accounting EE
l10n_bg_hr_contract_sign	Electronic signing of employment contracts EE, 150 EUR
l10n_bg_config_plugins_payroll	Accounts for SSI, NHIF, ASPF, GFLA EE, 20 EUR
l10n_bg_config_plugins_nsi_expences	Expense 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

Module	Description
l10n_bg_report_theme	Section theme (Header/Article/Footer), SF fonts, logo colors
l10n_bg_sign_report_theme	User signatures in QWeb templates EE, 25 EUR
l10n_bg_invoice_copy	Watermark "COPY" on invoices
l10n_bg_report_stock	Acceptance-delivery protocols for warehouse
l10n_bg_sale_order_delivery_note	Goods receipt for sales
l10n_bg_reports_audit_assets	Depreciation reports EE
l10n_bg_assets	Tax 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

Module	Description
l10n_bg_tariff_code	TARIC/HS/CN codes with EU API integration
taric_ai_classifier	AI classification of goods via Claude AI
l10n_bg_intrastat	Intrastat XML declarations — arrivals/dispatches EE, 150 EUR
l10n_bg_customs_currency_rate_live	Exchange rates from Customs Agency Enterprise
l10n_bg_customs_rate	Customs 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

Module	Description
l10n_bg_api_nra	REST API to NRA — declarations D1, D6, ETZ, VAT, VIES
l10n_bg_bank_wallet	Wallet 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

Module	Description
l10n_bg_erp_net_fp	ErpNet.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

Tax	Seq	Base Tag	Tax Account	Tax Tag
20% VAT	101	+11	453200	+21
9% VAT	111	+13	453200	+24
0% Export	121	+14	—	—
0% ICS	122	+15	—	—
0% Exempt	125	+19	—	—
0% Art. 69(2)	501	+23	—	—

Tax Structure — Purchases

Tax	Seq	Base Tag	Tax Account	Tax Tag
20% FTC	201	+31	453100	+41
20% PTC	202	+32	453100	+42
20% OTC	203	+30	453100	+30
9% FTC/OTC	211-212	Analogous 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_type	bg_move_type	type_vat	doc
out_invoice	standard	standard	01
out_refund	standard	standard	01
in_invoice	standard	standard	01
in_refund	standard	standard	01

EU B2B

move_type	bg_move_type	type_vat	doc
out_invoice	standard	standard	01
out_refund	standard	standard	01
in_invoice	protocol	117_protocol_84	09
in_refund	protocol	117_protocol_84	09

Outside EU

move_type	bg_move_type	type_vat	doc
out_invoice	standard	out_customs	01
out_refund	standard	out_customs	01
in_invoice	customs	in_customs	07
in_refund	customs	in_customs	07

Art. 82(2)

move_type	bg_move_type	type_vat	doc
in_invoice	protocol	117_protocol_82_2	09
in_refund	protocol	117_protocol_82_2	09

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 <command>"

# 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/<repo>/<module> .'"

# 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/<repo> && 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 <module> -d <db> --stop-after-init
5. Verification
   XML-RPC test, check taxes, fiscal positions, TAMs

Saved Instances

Name	URL	Type
octa-light	portal4.octa-light.com	Production
demo-18	demo-18.odoo-shell.space	Demo/Test
alpinter-bulgaria	world-of-tents.odoo.accomodata.net	Production
miv-electronics	erp.mivelectronics.com	Production
terraros-commerce	www.odoo-shell.dev	Production + 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

1. In what order should I install the modules?

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

2. Is an Enterprise license required?

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

3. How to check if the taxes are correct?

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

4. What to do if the plugins don't create taxes?

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

5. How to update the modules?

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

6. How to add a new module on a server with Docker?

docker exec -u 0 odoo sh -c 'cd /var/lib/odoo/.local/share/Odoo/addons/18.0 && \
  ln -sf /opt/odoo/rv/<repo>/<module> .'
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/<module>

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