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

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:

Go to Settings → Accounting → Company Configuration
Fill in UIC/BULSTAT, VAT number, address
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:

Grant permissions: User → Groups → "Crypto Wallet: Administrator"
The "Crypto Wallets" menu appears in the main menu
For InfoPay: Settings → Company → InfoPay Unique ID + Access Token
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:

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)
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
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
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:

Configure NKPD positions: HR → Configuration → NKPD
Set MOD for each KID activity
Create salary structures for different contract types
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:

Settings → Report Theme → choose logo, colors, font
Configure sections: Header, Article, Footer
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:

Products → fill in TARIC/CN codes
For AI classification — configure Claude API key in Settings
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:

Settings → Company → NRA configuration
Enter API key from portal.nra.bg
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:

POS → Configuration → Fiscal Printers → Add
Enter the printer's IP address and port
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.

Core

Base, chart of accounts, taxes, fiscal positions

Bank

Wallet and InfoPay

VAT

Reports, protocols, TAMs

Payroll

Payroll, leaves, NKPD

Reports

Themes, documents, assets

Trade

Tariffs, customs, Intrastat

NRA

API integration

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 "

# 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

Development (local)
Code change → git commit → git push origin 18.0
Pull on server
ssh server "cd /opt/odoo/rv/ && git pull origin 18.0"
Symlinks (if new module)
docker exec -u 0 odoo sh -c 'cd addons/18.0 && ln -sf ...'
Restart / Upgrade
docker restart odoo or docker exec odoo odoo -u -d --stop-after-init
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

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:

Check logs: docker logs odoo --tail 100
Debug Mode: Settings → Activate Developer Mode
Test XML-RPC: python3 odoo_connect.py
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

InstaLLATION

Follow us

Installation Guide

What does the localization include?

Modules are in 5 repositories

Table of Contents

Group "Core" — mandatory base

Group "Bank" — banking integration and payments

Encrypted Wallet

InfoPay Synchronization

IBAN Identification

Additional modules (EE)

l10n_bg_infopay_online

l10n_bg_account_bank_statement_import_mt940

l10n_bg_account_statement_import_mt940

Group "VAT" — tax administration and reporting

reports_audit

config_plugins_art_82_2

Operation types (quick reference)

Group "Payroll" — payroll and HR

Full Salary Structure

NKPD Classifier

61 Leave Types

Group "Reports" — themes and documents

Group "Trade" — tariffs, customs, Intrastat

Group "NRA" — API integration

OAuth 2.0

Declarations

VAT and VIES

Validation

Group "POS" — fiscal printer

Group "Multilingual"

partner_multilang

l10n_bg_multilang

l10n_bg_mrp_multilang

l10n_bg_project_multilang

Full Installation Step by Step

Core

Bank

VAT

Payroll

Reports

Trade

NRA

POS

Reference Configuration (Raytron)

Tax Structure — Sales

Tax Structure — Purchases

Reverse Charge (Group taxes via 430)

Tax Action Maps (by fiscal position)

Connection and Management Methods

Saved Instances

Claude Code — trained assistant for Bulgarian localization

Memory

How to Provide the Training

What is NOT trained (limitations)

Example Commands for Claude Code

Frequently Asked Questions

1. In what order should I install the modules?

2. Is an Enterprise license required?

3. How to check if the taxes are correct?

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

5. How to update the modules?

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

Technical Support

`l10n_bg_infopay_online`

`l10n_bg_account_bank_statement_import_mt940`

`l10n_bg_account_statement_import_mt940`

`partner_multilang`

`l10n_bg_multilang`

`l10n_bg_mrp_multilang`

`l10n_bg_project_multilang`