# Автоматизация на ДДС за НАП: Пълно ръководство за изграждане на ДДС модул (и как да ползваме AI за целта)

## 1. Въведение
Управлението на ДДС (Данък Добавена Стойност) в България е строго регулиран процес, който изисква генерирането на специфични текстови файлове в точно определен формат (fixed-width) и кодировка (Windows-1251). За всеки софтуерен инженер или счетоводител, целта е автоматизация: от първичния документ (фактура) до крайните файлове за подаване в портала на НАП.

В тази статия ще разгледаме структурата на един ДДС модул и как да инструктираме изкуствен интелект (AI) да ни помогне в разработката му.

---

## 2. Анатомия на ДДС модула за България

Един стандартен ДДС модул се състои от три основни компонента:
1. **Дневник на покупките (`POKUPKI.TXT`)**: Регистър на всички получени доставки.
2. **Дневник на продажбите (`PRODAJBI.TXT`)**: Регистър на всички извършени доставки.
3. **Справка-декларация (`DEKLAR.TXT`)**: Обобщен документ, който сумира данните от дневниците в специфични "клетки" (напр. кл. 01 за облагаеми доставки с 20%).

### Технически изисквания:
- **Формат**: Фиксирана ширина на колоните (Fixed-width text). Всеки символ има точно определена позиция.
- **Кодировка**: **Windows-1251** (CP1251). Използването на UTF-8 ще доведе до грешка при валидация в НАП.
- **Разделител на редове**: `CRLF` (Windows стил).

---

## 3. Как да "накараме" AI да ни напише ДДС модул?

За да получите работещ код от AI (като GPT-4, Claude или Gemini), трябва да преминете през няколко етапа на инструктиране (Prompt Engineering).

### Етап 1: Дефиниране на структурата на данните
Не казвайте просто "напиши ми ДДС модул". Вместо това подайте схемата:
> "Напиши ми клас на [Language - напр. Python/TypeScript], който представлява запис в ДДС дневник за продажби. Полетата трябва да включват: Номер на документ (20 символа), Дата, ИН на контрагент (15 символа), Име (50 символа), Данъчна основа 20%, ДДС 20%."

### Етап 2: Логика за форматиране (Padding)
Най-трудната част е подравняването. Инструктирайте AI така:
> "Създай функция `to_fixed_width(text, length)`, която допълва текста с интервали отдясно до достигане на `length`. Ако текстът е по-дълъг, трябва да бъде отрязан."

### Етап 3: Кодиране и експорт
> "Напиши метод за експорт на списък от тези записи към файл `PRODAJBI.TXT`. Важно е файлът да бъде записан в кодировка `windows-1251` и всяка сума да бъде форматирана с 2 знака след запетаята (напр. 100.00)."

---

## 4. Пример за "Перфектния Промпт" (Master Prompt)

Ако искате AI да изгради цялата архитектура, използвайте следния детайлен промпт:

> **Промпт:**
> "Действай като Senior Backend Engineer. Трябва да разработим модул за генериране на ДДС декларации за НАП (България).
> 
> **Спецификации:**
> 1. Създай модели за `VatPurchaseEntry` и `VatSalesEntry` с полета за документ №, дата, ЕИК на контрагент, име на контрагент и суми за ДО и ДДС (20%, 9%, 0%).
> 2. Реализирай логика за сумиране на тези записи в обект `VatDeclaration`, който изчислява клетките:
>    - Клетка 01: Сума на ДО 20% от продажби.
>    - Клетка 02: Сума на ДДС 20% от продажби.
>    - Клетка 31: Сума на ДО с право на пълен данъчен кредит (покупки).
>    - Клетка 40: Общо начислен ДДС.
>    - Клетка 41/42: Резултат (за внасяне или възстановяване).
> 3. Напиши генератор за `DEKLAR.TXT`, който е текстов файл с фиксирана ширина, където всяка клетка заема 15 символа, а заглавната част съдържа ИН на фирмата (15) и Период YYYYMM (6).
> 4. Осигури конвертирането на крайния низ към Windows-1251.
> 
> Използвай чисто обектно-ориентиран подход и добави коментари на български език."

---

## 5. Специфични "капани" и как да ги избегнем

1. **Кодове на документи**: Уверете се, че AI знае за кодовете (01 - Фактура, 02 - Дебитно известие, 03 - Кредитно известие). Кредитните известия винаги влизат с **отрицателен знак** в сумите, но като положителни числа в дневника (в зависимост от софтуера за подаване, но стандартно сумите са със знак).
2. **Валидация на ЕИК**: Добавете проверка за валидност на Булстат/ДДС номер (алгоритъмът за проверка на 9 и 13-цифрени кодове).
3. **Закръгляне**: НАП изисква сумите да са точно до втория знак. Използвайте типа `Decimal` (в Python) или цент (Integer) за изчисленията, за да избегнете грешки от плаваща запетая (float).

---

## 6. Примери за файлове
В подпапката `nap_examples/` сме приложили реални структури на файловете:
- `DEKLAR.TXT` - Пример за справка-декларация.
- `POKUPKI.TXT` - Дневник на покупките с един примерен запис.
- `PRODAJBI.TXT` - Дневник на продажбите с един примерен запис.

Тези файлове могат да бъдат използвани като референция при тестване на вашия нов ДДС модул.

---
*Автор: AI Assistant*
*Дата: 16 Март 2026*
