Doktally — фактуриране, ДДС и отчетност за малък бизнес
Накратко
Doktally е моят собствен SaaS за отчитане на време, договори, таксуване, фактуриране, банкови извлечения и ДДС. Разделен е на шест Spring Boot услуги зад Spring Cloud Gateway, с Keycloak за идентичност, RabbitMQ за фонова работа и Angular клиент. Ядрото му е механизъм за таксуване, който може да обясни всяка сума, която създава, и покрива българските особености (дневници за НАП, VIES, данни от БНБ, смяната към евро), които общите инструменти пропускат.
Подзаглавие
Multi-tenant платформа за фактуриране и ДДС за малки български фирми, изградена и поддържана от един човек.
Област
Фактуриране / ДДС / Малък бизнес
Потребители
Фрийлансъри, еднолични търговци и малки фирми в България, както и счетоводителите, които работят с тях.
Роля
Основател / продуктов инженер
Предизвикателство
Издаването на фактура е лесната част. Преди нея идват въпросите, които я правят вярна или грешна: кои часове се таксуват, по каква ставка в деня, в който са отработени, по кой договор, разпределени по кои проекти и дали някой от тях вече не е фактуриран. След нея идват плащанията, кредитните известия, напомнянията, покупките, дневниците по ДДС за НАП и въпросът колко всъщност е спечелила фирмата това тримесечие. Малките фирми отговарят на тези въпроси в няколко инструмента и таблици, а грешките излизат месеци по-късно.
За какво отговарях
Продуктови решения и поетапният план, дизайн на услугите, реализация на бекенда и интерфейса, интеграции с файловете на НАП, VIES, БНБ, банките и Keycloak, процесът на издаване, CI, внедряване с Docker, архиви и наблюдение.
Подход
Разделение на услуги по бизнес области, идентичност и лицензиране на входа, а бавната работа (PDF, имейли, експорти) – през RabbitMQ. В механизма за таксуване парите са BigDecimal, изчислените стойности стоят отделно от човешките корекции, издаденото се замразява, а всяко число може да се обясни от източниците си.
Резултати
Започнах Doktally през март 2024 г., за да водя документите на собствената си фирма, и той прерасна в цялостен продукт. Версия 1.0 (пролетта на 2026 г.) покриваше документи, покупки, внасяне на ДДС файлове, отчитане на време, табла, известия и лицензиране.
Фаза 1 след това го превърна в инструмент за таксуване за изпълнители изобщо: договори с условия по дати и дневник на промените, фиксирани цени, абонаменти с включени часове, периодични услуги, защити за верността на таксуването, документи на езика на клиента, номериране по юридическо лице, експорт на данните, съпоставяне на банкови извлечения и защитен линк към фактурата, който клиентът може да потвърди или оспори. Няколко фирми (tenants) работят в една инсталация, всяка със свои потребители, роли, номериране и лиценз.
Това е проект на един човек: аз решавам какво да влезе, проектирам услугите, пиша Java и Angular кода и поддържам продукционната среда.
Подробности
Обзор
Започнах Doktally през март 2024 г., за да водя документите на собствената си фирма, и той прерасна в цялостен продукт. Обработва фактури и други документи, банкови извлечения, покупки, дневници по ДДС, отчитане на време, договори, календар с падежи, табла и известия за няколко фирми (tenants) в една инсталация.
Това е проект на един човек: аз решавам какво да влезе, проектирам услугите, пиша Java и Angular кода и поддържам продукционната среда.
Архитектура
flowchart TD
W[Angular 22 + PrimeNG клиент] --> G[Spring Cloud Gateway]
G --> KC[Keycloak]
G --> LIC[Licensing service]
G --> INV[Invoice service]
G --> USR[User service]
G --> CAT[Catalog service]
G --> NOT[Notification service]
INV --> MQ[RabbitMQ]
MQ --> NOT
NOT --> MAIL[Имейл / в приложението / WebSocket]
INV --> DB[(MongoDB + GridFS)]
USR --> DB
CAT --> DB
LIC --> DB
- Gateway (Spring Cloud Gateway, WebFlux): единна входна точка, проверка на JWT спрямо Keycloak, идентичността се извежда наново на входа, проверка на лиценза за всеки модул и функция с кратък кеш, таймаути и circuit breaker за всеки маршрут.
- Invoice: клиенти, проекти, договори, отработено време, правила и графици за таксуване, фиксирани цени, документи, номериране, преходи между статуси, плащания, банкови извлечения, покупки, импорти, справки, PDF и прикачени файлове в GridFS.
- User: организации, членове и роли, профили, регионални настройки и настройки за фактурите, табла и колони.
- Catalog: артикули и услуги по конвенциите на SAF-T.
- Notification: имейл шаблони, известия в приложението и в календара, получавани през RabbitMQ.
- Licensing: кои модули и функции може да ползва дадена фирма, издадени като подписани токени и управлявани от отделна част License manager.
Всичко работи на Java 25 и Spring Boot 4 с MongoDB. Angular клиентът използва PrimeNG и ECharts.
Изпращане на фактура
sequenceDiagram
participant U as Потребител
participant UI as Angular клиент
participant GW as Gateway
participant INV as Invoice service
participant MQ as RabbitMQ
participant N as Notification service
U->>UI: Изпрати фактура
UI->>GW: POST заявка (JWT)
GW->>GW: Проверка на лиценза за модула
GW->>INV: Препращане
INV->>INV: PDF, записан в GridFS
INV->>MQ: Събитие за изпращане
INV-->>UI: Приета (статус: изпраща се)
MQ->>N: Доставяне на събитието
N->>N: Шаблон, изпращане на имейл
N-->>INV: Статус на доставката
INV->>INV: Смяна на статуса + запис в историята
N-->>U: Известие в приложението
Заявката връща отговор веднага щом работата е поставена в опашката. PDF-ът и имейлът се правят във фонов режим, а статусът и историята на документа се обновяват, когато пристигне резултатът. Съобщенията минават през outbox с потвърждение от брокера, получателите са идемпотентни, а неуспешните доставки отиват в dead-letter опашки, вместо да изчезнат. Документът пази и на кого, как и кога е изпратен, така че по-късни промени в контактите на клиента не пренаписват тази история.
От часовете до фактура, която се обяснява сама
Повечето скорошна работа е в механизма за таксуване, защото там малките грешки струват истински пари.
- Всеки час по ставката от своя ден. Ставките имат дати на влизане в сила по проект или по договора с клиента. Промяна на ставка, въведена на 15 октомври със сила от 1 октомври, преизчислява нефактурираното време и показва точно кои вече издадени фактури би засегнала, без да ги пренаписва.
- Договорите определят условията. Клиентът може да има един действащ договор за всеки ден, с жизнен цикъл (чернова, активен, изтекъл, прекратен), анекси и удължения, минимум и максимум часове или стойност и напомняния преди сроковете за предизвестие.
- Правилата разпределят часовете. Часовете за таксуване на клиента могат да останат по проекта, в който са записани, или да се разпределят по съотношение или поравно между проектите в периода. Фактурата пази разпределението, с което е създадена.
- Фиксираната цена се таксува веднъж. Времето по проект с фиксирана цена се отчита за справки, но един ред във фактурата таксува договорената сума, никога часовете. Анексите, кредитните известия и изричното връщане за таксуване пазят цената от двойно таксуване или загуба.
- Проверки преди създаване. Точно преди фактурата да бъде създадена или издадена, Doktally търси проблеми, които биха я направили грешна (липсваща ставка, недействащ договор, разлика във валутата, цена, задържана от друга чернова). Грешките я спират; предупрежденията могат да се приемат.
- Всеки ред се обяснява сам. „Как е изчислен този ред“ показва часове × ставка = сума, правилото и договора зад ставката и всеки запис по дни. Ръчната промяна се пази като корекция с причина, до изчислената сума.
- Времето се заключва след таксуване. Един запис може да е само в една фактура. Черновата резервира времето си, издадената фактура го заключва, а анулиране или кредитно известие не го освобождава, освен ако някой изрично не го върне за таксуване.
Българската част
Общите програми за фактуриране не познават файловете, които българските фирми обменят с НАП. Doktally внася дневниците за продажби и покупки, справките-декларации по ДДС и VIES декларациите, подадени към НАП, премахва дублираните записи по бизнес ключ и ги превръща в справка по ДДС с проверки: нетна позиция по ДДС, начислен срещу приспаднат данък по периоди, дневници за покупки и продажби и месеците, в които дневниците, справката и VIES се разминават. ДДС номерата се проверяват във VIES, българските банки се разпознават по IBAN, а курсовете идват от БНБ. Фактури, кредитни и дебитни известия и имейлите към тях се издават на езика на клиента.
След версия 1.0: пари навън и навътре
- Банкови извлечения с причини. CAMT.053, MT940 или CSV на банката се внасят веднъж, плащанията се съпоставят с фактурите по основанието, оставащата сума и платеца, всяко предложение казва защо, а крайното салдо на всеки месец се проверява спрямо книгите. Разлика означава липсващо извлечение.
- Смяната към евро. Сметка, превърната от лева, пази старите си месеци в лева, дневниците по ДДС отпреди 2026 г. се превръщат при внасяне, а левът и еврото се съпоставят по фиксирания курс 1,95583.
- Абонаменти и периодични услуги. Месечна такса с включени часове, прехвърляне до таван и допълнителни часове по ставката от своя ден; фиксирани услуги като хостинг, таксувани всеки период, всяко появяване точно веднъж.
- Абонаменти при доставчици. Какво плаща фирмата всеки месец или година, подновявания и срокове за отказ и напомняне, когато фактура от доставчик, която е трябвало да дойде, още липсва.
- Защитен линк към фактурата. Клиентът отваря фактурата без профил, изтегля я и я потвърждава или оспорва с коментар; оспорването пристига като задача, а правният статус на фактурата не се променя.
- Чеклист за края на месеца. Нефактурирани часове, просрочени фактури, оспорвания, срокове за предизвестие и неуспешни периодични документи, всяко се затваря само, когато бъде решено.
Всяко от тях е описано със снимки на отделна страница: решения за Doktally.
Решения, които имаха значение
Парите са BigDecimal навсякъде. Първоначално ключовете при импорт използваха Double; те бяха мигрирани към BigDecimal заедно с останалия финансов модел. Сумите в различни валути се превалутират изрично и се показват по валути.
Изчисленото и коригираното стоят отделно. Създаденият ред пази това, което казват времето и ставката. Промяната от човек е отделна корекция с причина, така че двете винаги могат да се сравнят и изградят наново.
Издадено значи замразено. Издаването на фактура записва клиента, артикулите, ДДС и обяснението на всеки ред. Преименуване на клиента, смяна на ставка или анекс към договора по-късно никога не променят изпратеното; приложението показва какво се е променило и предлага кредитно или дебитно известие.
Документите имат state machine и история. Преходите между статуси са изрични и настройваеми, а всяка промяна (полета, редове, прикачени файлове, плащания, връщания за таксуване) се записва със старата и новата стойност. Потребителите могат да добавят бележки към записите в историята, което помага, когато счетоводителят пита защо нещо е променено.
Регресионни тестове за пътищата на парите. Всеки важен за таксуването сценарий има свой тест от край до край върху малък набор от данни, отбелязан така, че целият набор за таксуване и договори се пуска с една команда. Самите демо данни също се проверяват, че създават и издават фактурите си без грешки.
Бавната работа минава през опашката. PDF файловете, имейлите и експортите никога не блокират заявка. Потребителят получава известие, когато файлът е готов.
Ограничаване по фирма в слоя за данни. Търсенията минават през заявки, съобразени с фирмата, като findByIdAndTenantId, така че данните на една фирма не могат да изтекат към друга заради пропуснат филтър. Ролите (собственик, администратор, счетоводител, потребител) се налагат в API-то и се виждат в менюто.
Лицензиране на входа. Gateway-ят решава кои модули и функции може да извиква дадена фирма, така че бизнес услугите не съдържат проверки за лицензи. Лицензите се проверяват наново на всеки 30 секунди, така че спирането на лиценз действа почти веднага.
Поддържан от един човек. Един Docker Compose файл за продукция с Caddy за HTTPS, скриптове за архивиране и възстановяване на MongoDB, метрики в Prometheus и превключвател, който зарежда пълно демо. Всяко внедряване е манифест на издание от независимо версионирани услуги, всяка като непроменим образ, изграден веднъж.
Следващи стъпки
- директно подаване на декларации 1 и 6 към НАП през неговото API, щом подписването с квалифициран електронен подпис заработи от сървъра
- асиметрично подписани токени за правата (RS256 / JWKS), плащания и портал за самообслужване на лицензите
- измерване на използването по фирми
Технологии
Java 25, Spring Boot 4, Spring Cloud Gateway, Angular 22, PrimeNG, ECharts, MongoDB, RabbitMQ, Keycloak, Docker, Caddy, Prometheus
Ангажимент
PERSONAL_PRODUCT
Период
2024-03 – досега
Решения
- Дневниците по ДДС директно от файловете за НАП
- Фактури, които обясняват всяка сума
- Преминаването към евро без хаос
- Плащания, съпоставени с причина, и салдо, което трябва да съвпадне
- Никога повече забравена фактура от доставчик
- Договори, които помнят всяка промяна
- Абонаменти с включени часове, прехвърляне и таван
- Чеклист за края на месеца, който намира забравените пари
- Данните са ваши и можете да ги вземете
- Командировки, отчетени и префактурирани наведнъж