Ръководство за инсталация
Българска локализация за Odoo 18 — 50+ модула, 5 репозитория, пълен цикъл на българското счетоводство
ДДС Заплати Банкиране Митници НАП Интрастат
Какво включва локализацията?
Българската локализация за Odoo 18 е комплект от 50+ модула, организирани в функционални групи. Тя обхваща целия цикъл на българското счетоводство — от план сметка и декларации по ДДС до заплати, митнически операции и банково интегриране.
Модулите са в 5 репозитория
| Репо | Лиценз | Модули | Описание |
|---|---|---|---|
| l10n-bulgaria | LGPL-3 | 26 | Общинско издание — основно |
| l10n-bulgaria-ee | OPL-1 | 18 | Корпоративно издание — заплати, активи, банкиране |
| l10n-bulgaria-enterprise | OPL-1 | 2 | Корпоративно специализирано — ДДС, митници |
| l10n-bulgaria-expert | OPL-1 | 5 | Експерт — данъчна администрация, InfoPay |
| l10n-bulgaria-oca | LGPL-3 | 29 | Съвместими варианти с OCA |
Съдържание
- Група "Основна"
- Група "Банка"
- Група "ДДС"
- Група "Заплати"
- Група "Доклади"
- Група "Търговия"
- Група "НАП"
- Група "POS"
- Група "Многоезичен"
- Картите на данъчните действия
- Свързване и управление
- Асистент по кода Клод
- Често задавани въпроси
Група "Ядро" — задължителна база
Команда: инсталирай ядро
| Модул | Описание |
|---|---|
| l10n_bg_config | Централна конфигурация, архитектура на миксини, валидиране на UIC, криптиране |
| l10n_bg_city | База данни EKATTE — 28 региона, 265 общини, 5000+ населени места |
| l10n_bg_address_extended | Разширено адресиране по български стандарт |
| l10n_bg_tax_offices | Офиси на НАП и териториални дирекции |
| l10n_bg_company_registry | Интеграция с Търговския регистър (API) |
| partner_multilang | Многоезични имена с кирилска транслитерация |
| l10n_bg_multilang | Многоезична поддръжка за партньори, компании, служители |
| markdown_viewer_locale | Локализиран преглед на документацията |
Зависимости
база, акаунт, контакти, HR, склад
Какво прави
- Създава българската счетоводна схема
- Конфигурира данъци (20%, 9%, 0% — продажби и покупки)
- Създава фискални позиции (Вътрешен, ЕС B2C, ЕС B2B, Извън ЕС)
- Зарежда географската база данни на България
- Активира многоезична поддръжка (BG/EN)
След инсталацията:
- Отидете на Настройки → Счетоводство → Конфигурация на компанията
- Попълнете UIC/BULSTAT, номер на ДДС, адрес
- Проверете плана на сметките в Счетоводство → Конфигурация → Сметки
Група "Банка" — банково интегриране и плащания
Команда: инсталирайте банка
| Модул | Описание |
|---|---|
| l10n_bg_bank_wallet | Шифрован портфейл с ключ (PBKDF2+Fernet) |
| l10n_bg_infopay | InfoPay API — синхронизация на извлечения и плащания |
Шифрован портфейл
Създава шифрован портфейл за всеки потребител — API ключове, RSA ключове, сертификати
Синхронизация с InfoPay
Банкови извлечения, единични и пакетни плащания (BGN/EUR)
IBAN идентификация
Автоматична идентификация на банкови сметки по IBAN
Зависимости:сметка, база, уеб
След инсталацията:
- Предоставете разрешения: Потребител → Групи → "Крипто портфейл: Администратор"
- Менюто "Крипто портфейли" се появява в основното меню
- За InfoPay: Настройки → Компания → Уникален ID на InfoPay + Токен за достъп
- Банкови журнали → попълнете "ID на сметката в InfoPay"
Допълнителни модули (EE)
l10n_bg_infopay_online
Разширен интерфейс с пакетни плащания Expert, 15 EUR
l10n_bg_account_bank_statement_import_mt940
MT940 импорт EE
l10n_bg_account_statement_import_mt940
MT940 импорт CE
Група "ДДС" — данъчно администриране и отчитане
Команда: инсталирайте ДДС
| Модул | Описание |
|---|---|
| l10n_bg_reports_audit | SQL двигател за одит, 14 модела, тагове на акаунти |
| l10n_bg_reports_config | Конфигурационни изгледи за отчети |
| l10n_bg_vat_reports | Декларация по ДДС, журнали за продажби/покупки, VIES EE, 250 EUR |
| l10n_bg_report_vat | Разширени отчети по ДДС с CSV/ZIP/PDF експорт за NRA Enterprise, 250 EUR |
| l10n_bg_tax_admin | Протоколи по чл. 117, митнически декларации, TAMs Expert, 300 EUR |
| l10n_bg_config_plugins_art_69_2 | Чл. 69(2) Закон за ДДС — място на доставка в друга държава членка на ЕС |
| l10n_bg_config_plugins_art_82_2 | Чл. 82(2) Закон за ДДС — обратно начисляване за услуги от ЕС |
Зависимости:акаунт, склад, покупка_склад, продажба
reports_audit
- SQL изгледи за журнал на покупки, журнал на продажби, VIES
- Тагове на акаунти за клетки на декларация по ДДС (+11, +12_1, +12_2, +13, +21, +22, +31, +41, +42...)
tax_admin
- Протоколи по чл. 117 Закон за ДДС (автоматично за ICA, услуги от ЕС)
- Митнически декларации (SAD, MRN, тарифни ставки)
- Картографски действия по данъци — "мозъкът" на системата
- Два нови типа данъци: митническа ставка и частна ставка
- Частно ползване с коефициент
config_plugins_art_82_2
- Фискална позиция "0% Чл. 82(2)" за услуги от ЕС
- Групов данък с обратно начисляване (дължимо + вземаемо чрез акаунт 430)
- Картографиране: 20%/9%/0% → 0% PTC Чл. 82(2)
След инсталацията:
- Проверете фискалните позиции:Счетоводство → Конфигурация → Фискални позиции — Вътрешни (последователност=10), ЕС B2C (20), ЕС B2B (30), Извън ЕС (40), 0% Чл. 69(2) (последователност=60), 0% Чл. 82(2) (последователност=61)
- Конфигурирайте картите за данъчни действия(ако имате tax_admin) — Вътрешни: 4 TAMs, ЕС B2B: 4 TAMs, Извън ЕС: 4 TAMs, Чл. 82(2): 2 TAMs
- Проверете данъчните етикети:Дължими Чл.82(2): база +12_2, данък +22 / Платими Чл.82(2): база +31, данък +41 / Дължими ICA: база +12_1, данък +22 / Платими ICA: база +31, данък +41
- Приложете шаблоните(ако art_69_2/art_82_2 са инсталирани): Настройки → Счетоводство → Приложи шаблон на счетоводната схема
Видове операции (бърза справка)
| Операция | Закон за ДДС Чл. | Документ | Тип ДДС | Тип документ |
|---|---|---|---|---|
| ICA | 13, 62, 84, 117 | Протокол | 117_protocol_84 | 09 |
| Услуги от ЕС | 21, 82, 117 | Протокол | 117_protocol_82_2 | 09 |
| Внос | 57 | Митническа декларация | in_customs | 07 |
| Лично ползване | 9(3), 117 | Протокол | 117_protocol_6_3 | 09 |
| Триъгълна | 15, 117 | Протокол | 117_protocol_15 | 09 |
| ICS | 7, 28 | Фактура 0% | standard | 01 |
| Износ | 28 | Фактура 0% | out_customs | 07 |
Група "Заплати" — заплати и HR
Команда: инсталирай заплати
| Модул | Описание |
|---|---|
| l10n_bg_payroll_classifications | NKPD позиции и KID дейности с MOD ставки |
| l10n_bg_hr_holidays | 61 вида отпуски по Кодекса на труда (17 НЗОК, 4 годишни, 8 граждански, 7 майчинство...) |
| l10n_bg_hr_payroll | Заплати с изчисления за ОСИ/ЗО/ДО/ОАВИ EE, 250 EUR |
| l10n_bg_hr_payroll_account | Заплати → счетоводство EE |
| l10n_bg_hr_contract_sign | Електронно подписване на трудови договори EE, 150 EUR |
| l10n_bg_config_plugins_payroll | Сметки за ОСИ, НЗОК, АСПФ, ГФЛА EE, 20 EUR |
| l10n_bg_config_plugins_nsi_expences | Сметки за разходи по НСИ — серии 601.x, 602.x EE, 15 EUR |
Зависимости:hr, hr_payroll, hr_contract, hr_holidays
Пълна структура на заплатите
Автоматично изчисление на осигурителните вноски по българското законодателство
NKPD Класификатор
7800+ позиции, KID класификатор с минимален осигурителен доход (MOD)
61 вида отпуски
По Кодекса на труда + електронно подписване на трудови договори
След инсталацията:
- Конфигурирайте NKPD позиции: HR → Конфигурация → NKPD
- Задайте MOD за всяка KID дейност
- Създайте структури на заплатите за различни типове договори
- Ако е необходимо — приложете плъгини за заплати и НСИ от Настройки
Група "Доклади" — теми и документи
Команда: инсталирайте доклади
| Модул | Описание |
|---|---|
| l10n_bg_report_theme | Тема на секцията (Заглавие/Статия/Футер), шрифтове SF, цветове на логото |
| l10n_bg_sign_report_theme | Подписи на потребители в QWeb шаблони EE, 25 EUR |
| l10n_bg_invoice_copy | Воден знак "Копие" на фактури |
| l10n_bg_report_stock | Протоколи за приемане-доставка за склад |
| l10n_bg_sale_order_delivery_note | Прием на стоки за продажби |
| l10n_bg_reports_audit_assets | Доклади за амортизация EE |
| l10n_bg_assets | Данъчна амортизация по български стандарти EE, 150 EUR |
Зависимости:уеб, продажба, сметка, склад, покупка
След инсталацията:
- Настройки → Тема на доклада → изберете лого, цветове, шрифт
- Конфигурирайте секции: Заглавие, Статия, Футер
- За фактури — проверете шаблона в Счетоводство → Конфигурация → Доклади
Група "Търговия" — тарифи, митници, Интрастат
Команда: инсталирайте търговия
| Модул | Описание |
|---|---|
| l10n_bg_tariff_code | TARIC/HS/CN кодове с интеграция на EU API |
| taric_ai_classifier | AI класификация на стоки чрез Claude AI |
| l10n_bg_intrastat | Intrastат XML декларации — пристигания/изпращания EE, 150 EUR |
| l10n_bg_customs_currency_rate_live | Обменни курсове от Агенция Митници Предприятие |
| l10n_bg_customs_rate | Бутон за митническа ставка на фактури EE |
Зависимости:сметка, склад, доставка_на_склад, сметка_интрастат
След инсталацията:
- Продукти → попълнете TARIC/CN кодове
- За AI класификация — конфигурирайте Claude API ключ в Настройки
- За Интрастат — задайте прагове и отговорно лице
Група "НРА" — API интеграция
Команда: инсталирайте nra
| Модул | Описание |
|---|---|
| l10n_bg_api_nra | REST API към НРА — декларации D1, D6, ETZ, ДДС, VIES |
| l10n_bg_bank_wallet | Портфейл за API ключове (зависимост) |
Зависимости:основа, l10n_bg_config, l10n_bg_bank_wallet
OAuth 2.0
Аутентикация с НРА
Декларации
Форма 1, Форма 6, ETZ
ДДС и VIES
Декларации по ДДС и VIES
Валидиране
Ограничаване на скоростта и XML валидиране
След инсталацията:
- Настройки → Компания → конфигурация на НРА
- Въведете API ключ от portal.nra.bg
- Съхранете ключа в Крипто Портфейл
Група "POS" — фискален принтер
Команда: инсталирайте pos
| Модул | Описание |
|---|---|
| l10n_bg_erp_net_fp | Интеграция на ErpNet.FP за фискални принтери |
Зависимости: point_of_sale, account, bus, mail
След инсталацията:
- POS → Конфигурация → Фискални принтери → Добави
- Въведете IP адреса и порта на принтера
- Тествайте връзката
Група "Многоезичен"
Команда: инсталирай многоезичен
partner_multilang
Автоматична транслитерация Кирилица ↔ Латиница
l10n_bg_multilang
Многоезични партньори, компании, служители
l10n_bg_mrp_multilang
Многоезични работни центрове в MRP
l10n_bg_project_multilang
Многоезични задачи в Проект
Пълна инсталация стъпка по стъпка
Команда: инсталирай всичко
Важно: Ядрото трябва да бъде инсталирано ПЪРВО. Останалите групи могат да бъдат инсталирани в произволен ред.1
Ядро
База, план на сметките, данъци, фискални позиции
2
Банка
Портфейл и InfoPay
3
ДДС
Доклади, протоколи, TAMs
4
Заплати
Заплати, отпуски, NKPD
5
Доклади
Темите, документи, активи
6
Търговия
Тарифи, митници, Intrastat
7
НРА
API интеграция
8
POS
Фискален принтер
Референтна конфигурация (Raytron)
Данъчна структура — Продажби
| Данък | Последователност | Основен етикет | Данъчна сметка | Данъчен етикет |
|---|---|---|---|---|
| 20% ДДС | 101 | +11 | 453200 | +21 |
| 9% ДДС | 111 | +13 | 453200 | +24 |
| 0% Износ | 121 | +14 | — | — |
| 0% ICS | 122 | +15 | — | — |
| 0% Освободен | 125 | +19 | — | — |
| 0% Чл. 69(2) | 501 | +23 | — | — |
Данъчна структура — Покупки
| Данък | Последователност | Основен етикет | Данъчна сметка | Данъчен етикет |
|---|---|---|---|---|
| 20% FTC | 201 | +31 | 453100 | +41 |
| 20% PTC | 202 | +32 | 453100 | +42 |
| 20% OTC | 203 | +30 | 453100 | +30 |
| 9% FTC/OTC | 211-212 | Аналогична структура с 9% ставка |
Обратен данък (Групови данъци чрез 430)
20% ЕС PTC (ICA)
Дължимо:основа +12_1, данък -100% 453200 +22, +100% 430
Получаемо:основа +31, данък +100% 453100 +41, -100% 430
0% ПТК Чл. 82(2)
Дължимо:основа +12_2, данък -100% 453200 +22, +100% 430
Получаемо:основа +31, данък +100% 453100 +41, -100% 430
Картите за данъчни действия (по фискална позиция)
Вътрешен
| тип_прехвърляне | bg_тип_прехвърляне | тип_ДДС | документ |
|---|---|---|---|
| изходяща_фактура | standard | standard | 01 |
| изходящо_възстановяване | standard | standard | 01 |
| входяща_фактура | standard | standard | 01 |
| входящо_възстановяване | standard | standard | 01 |
ЕС B2B
| тип_прехвърляне | bg_тип_прехвърляне | тип_ДДС | документ |
|---|---|---|---|
| изходяща_фактура | standard | standard | 01 |
| изходящо_възстановяване | standard | standard | 01 |
| входяща_фактура | протокол | 117_protocol_84 | 09 |
| входящо_възстановяване | протокол | 117_protocol_84 | 09 |
Извън ЕС
| тип_прехвърляне | bg_тип_прехвърляне | тип_ДДС | документ |
|---|---|---|---|
| изходяща_фактура | standard | out_customs | 01 |
| изходящо_възстановяване | standard | out_customs | 01 |
| входяща_фактура | митници | in_customs | 07 |
| входящо_възстановяване | митници | in_customs | 07 |
Чл. 82(2)
| тип_прехвърляне | bg_тип_прехвърляне | тип_ДДС | документ |
|---|---|---|---|
| входяща_фактура | протокол | 117_protocol_82_2 | 09 |
| входящо_възстановяване | протокол | 117_protocol_82_2 | 09 |
Методи за свързване и управление
1. Odoo Мениджър за свързване (GUI)
Графично приложение за управление на връзките с инстанции на Odoo.
Стартиране:python3 odoo_connect.py
- Запазване на множество връзки с Odoo (URL, база данни, потребител, API ключ)
- Тест на връзката чрез XML-RPC
- Създаване на SSH псевдоними в ~/.ssh/config
- Зареждане, редактиране и изтриване на запазени връзки
Конфигурация:.odoo_connections/connections.json и ~/.ssh/config
2. XML-RPC (програматичен достъп)
Директен достъп до Odoo чрез XML-RPC за автоматизация.
Аутентификация:
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')
Типични операции:Инсталиране/надграждане на модули, четене/писане на данъци, фискални позиции, преразпределение на линии, създаване на карти за данъчни действия
3. Достъп до SSH сървър
Основни команди:
# Вход ssh terraros-commerce # Команда в Docker контейнер ssh server "docker exec -u 0 odoo <command>" # Изтегляне на репо ssh server "cd /opt/odoo/rv/l10n-bulgaria && git pull origin 18.0" # Рестартиране на Odoo ssh server "docker restart odoo" # Символна връзка за нов модул ssh server "docker exec -u 0 odoo sh -c \ 'cd addons/18.0 && ln -sf /opt/odoo/rv/<repo>/<module> .'" # Логове ssh server "docker logs odoo --tail 100"
4. Пълен цикъл на внедряване
- Разработка (локално)
Промяна на код → git commit → git push origin 18.0 - Изтегляне на сървъра
ssh server "cd /opt/odoo/rv/<repo> && git pull origin 18.0" - Символни връзки (ако е нов модул)
docker exec -u 0 odoo sh -c 'cd addons/18.0 && ln -sf ...' - Рестартиране / Надграждане
docker restart odoo или docker exec odoo odoo -u <module> -d <db> --stop-after-init - Проверка
XML-RPC тест, проверка на данъци, фискални позиции, TAMs
Запазени инстанции
| Име | URL | Тип |
|---|---|---|
| octa-light | portal4.octa-light.com | Производство |
| demo-18 | demo-18.odoo-shell.space | Демо/Тест |
| alpinter-bulgaria | world-of-tents.odoo.accomodata.net | Производство |
| miv-electronics | erp.mivelectronics.com | Производство |
| terraros-commerce | www.odoo-shell.dev | Производство + SSH |
Claude Code — обучен асистент за българска локализация
Claude Code (Opus 4.6) е обучен и конфигуриран да работи като пълнофункционален асистент за инсталация, конфигурация и поддръжка на българската локализация за Odoo 18.
Знания за изходен код
- Пълна анализа на жизнения цикъл на модулите на Odoo 18
- Граф на зависимостите, автомат на състоянията, последователност на зареждане
- ir.module.module, ir.model.data, _module_data_uninstall()
- Скриптове за миграция (предварителни/пост/крайни), хукове (pre_init/post_init/uninstall)
Знания за локализация
- Архитектура на 54+ модула в 5 репозитория
- Подробен анализ на l10n_bg_tax_admin
- SQL двигател на l10n_bg_reports_audit
- Данъчни отчети — декларации, журнали, VIES, формати на NRA
- Референтна данъчна конфигурация от Raytron
Практически умения
- XML-RPC връзка (GUI + програмно)
- Отдалечена инсталация и ъпгрейд на модули
- Проверка и корекция на данъчната конфигурация
- Създаване на данъчни действия, фискални позиции
- SSH достъп, Docker, управление на символни линкове
- Git операции — commit, push, pull
- Намиране и отстраняване на грешки
Памет
- Профил на потребителя (Росен, български разработчик на Odoo 18)
- Всички пътища на репозиториите (локални и сървърни)
- Конфигурация на активна инстанция (Raytron, Octa Light, Demo-18, Alpinter, Terraros)
- Основна инсталация на VM+Docker+Cloudflare сървър
- Групи за бърза инсталация на модули
- Инструкции CLAUDE.md, файлове с памет, автоматична памет
Как да предоставите обучението
За да работи Claude Code напълно с българската локализация нанова машина или в нов проект, следното трябва да бъде предоставено:
1. CLAUDE.md— инструкции за проекта
Език, памет, резюме при стартиране
/home/rosen/.../claude.ai/CLAUDE.md
2. Файлове с памет— натрупани знания
- user_profile.md — профил на потребителя
- project_l10n_bg_overview.md — архитектура на 54+ модула
- reference_repo_paths.md — пътища на хранилищата
- odoo18_module_lifecycle.md — инсталация на модули
- installation_guide_bg.md — това ръководство
- server_base_install_vm_docker.md — инсталация на сървър
- module_l10n_bg_tax_admin.md — анализ на tax_admin
- module_l10n_bg_reports_audit.md — анализ на reports_audit
- module_l10n_bg_vat_reports.md — анализ на ДДС отчети
- raytron_fiscal_config.md — референтна конфигурация
- raytron_tax_config_detailed.md — подробни данъчни шаблони
3. Odoo Connection Manager
- odoo_connect.py — GUI за управление на връзките
- .odoo_connections/connections.json — запазени инстанции
4. Достъп
- XML-RPC API ключове за Odoo инстанции
- SSH конфигурация (~/.ssh/config) за сървъри
- GitHub SSH ключове за push/pull
Какво НЕ е обучено (ограничения)
- Не може да се получи достъп до уеб интерфейса на Odoo (няма браузър)
- Не може да се приложат шаблони на Счетоводен план — това се прави от GUI
- Не може да се тестват фактури от край до край (само конфигурация)
- Не може да се генерират PDF отчети
- Не е обучен за специфично разгръщане на Odoo.sh
Примерни команди за Claude Code
"инсталирай ДДС в terraros-commerce" "провери данъците в octa-light" "поправи чл. 82(2) според референцията" "изтегли l10n-bulgaria на сървъра"
"създай символна връзка за l10n_bg_infopay" "стартирай конфигуратора" "покажи какво е инсталирано в demo-18"
Често задавани въпроси
1. В какъв ред трябва да инсталирам модулите?
Първо основните, след това по необходимост. Odoo автоматично разрешава зависимостите.
2. Изисква ли се лиценз за Enterprise?
Модулите, маркирани с (EE), изискват Enterprise. Модулите за общността работят с CE.
3. Как да проверя дали данъците са правилни?
Сравнете с референцията на Raytron — етикети, сметки, линии за преразпределение.
4. Какво да направя, ако плъгините не създават данъци?
Шаблоните се прилагат от Настройки → Приложи шаблон на график. Или конфигурирайте ръчно.
5. Как да актуализирам модулите?
ssh сървър "cd /opt/odoo/rv/l10n-bulgaria && git pull origin 18.0" docker restart odoo
6. Как да добавя нов модул на сървър с 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
Техническа поддръжка
В случай на проблеми:
- Проверете логовете: docker logs odoo --tail 100
- Режим на отстраняване на грешки: Настройки → Активирайте режим на разработчик
- Тест на XML-RPC: python3 odoo_connect.py
- Проверете символичните линкове: docker exec -u 0 odoo ls -la /var/lib/odoo/.local/share/Odoo/addons/18.0/<module>
Версия:2.0 |Дата:24.03.2026 |Съответствие:Закон за ДДС, Кодекс на труда, Кодекс за социално осигуряване, в сила от 01.01.2026
Ръководство за инсталиране и конфигуриране за българска локализация за Odoo 18 — 50+ модула, 5 репозитория, 9 групи за инсталиране