# Хостваните регистри вече разрешават включвания на управлявани цени

Да си го кажем направо: притежанията ви вече са перфектно записани в регистъра. Именно *цените* ви държат в цикъл на безкрайно преписване.

Тази асиметрия е най-старата и най-досадната задача в счетоводството с чист текст. Записвате покупка веднъж и тя остава завинаги в камък: `120 NWRB {41.80 USD, 2024-03-12}` заковава за постоянно количество, разход и дата. Нищо, което се случи след това, не променя тези факти. Цената обаче е точно обратното — тя е вярна точно за един ден и после тихо става грешна. Още по-лошо: грешна е по начин, който никоя проверка на баланса никога няма да улови, защото регистър с остарели цени все още се балансира перфектно.

Исторически подходът в Beancount за справяне с това беше да се изтеглят цени със скрипт и резултатът да се комитне. Работи и много хора са го автоматизирали. Но в крайна сметка това си остава скрипт, който трябва да гледате, cron задача, която поддържате, и файл, който постоянно merge-вате.

**Край на това.** За регистри, хоствани на beancount.io, нашият двигател вече се справя с това разрешаване нативно. Този пост описва точно какво току-що пуснахме, какво умишлено не пипнахме и — също толкова важно — какво още не сме изградили.

---

### Какво пуснахме

Хостван регистър в beancount.io вече може да съдържа директива `include`, която сочи към URL вместо към локално име на файл:

```beancount
; main.bean, in a hosted beancount.io ledger.
;
; This page is Bulgarian, so the quote currency is EUR. On another language of
; this site, use the currency in the list under the fence.

option "title" "Taxable brokerage"
option "operating_currency" "EUR"

; Only the hosted engine resolves the URL form, and upstream `include` takes a
; file glob — so the line is shown commented out here and this file still
; loads if you copy it to your own machine. Uncomment it in a hosted ledger.
; include "https://beancount.io/prices/AAPL-EUR"
```

**Внимание:** Ще трябва да влезете в профила си, преди да отворите този URL. Анонимните заявки се пренасочват към страницата за вход. Тази страница е на български, затова примерът използва евро — валутата, в която читателите тук най-често водят книгите си. След като се автентикирате, отворете [https://beancount.io/prices/AAPL-EUR](https://beancount.io/prices/AAPL-EUR) и потвърдете, че виждате стандартни директиви `price`. След това добавете този ред към хоствания си регистър.

Ако четете на друг език, използвайте обичайната валута за този език и само когато каталогът я посочва като котировка:

- English: `USD`, [https://beancount.io/prices/AAPL-USD](https://beancount.io/prices/AAPL-USD)
- 中文: `CNY`, [https://beancount.io/prices/AAPL-CNY](https://beancount.io/prices/AAPL-CNY). Този URL не е посочена двойка. Това е некоригираното затваряне на Databento за `AAPL-USD`, кроснато с `USD-CNY` на ЕЦБ.
- 日本語: `JPY`, [https://beancount.io/prices/AAPL-JPY](https://beancount.io/prices/AAPL-JPY)
- 한국어: `KRW`, [https://beancount.io/prices/AAPL-KRW](https://beancount.io/prices/AAPL-KRW)
- Deutsch, Français, Español, Italiano, Nederlands, Català, Português, Slovenčina и Български: `EUR`, [https://beancount.io/prices/AAPL-EUR](https://beancount.io/prices/AAPL-EUR). Българските книги, открити тази година, са в евро; каталогът също котира `BGN`, ако по-стар файл все още го използва.
- فارسی, Русский и Українська: каталогът няма `IRR`, `RUB` или `UAH`, така че няма двойка за отваряне. Изберете котировка, която той все пак посочва.

Каталогът на [https://beancount.io/prices/](https://beancount.io/prices/) се намира зад същия вход. Самата `AAPL-USD` е директна котировка от Databento, а не крос. Други акции от първи ред работят по същия начин — сменете тикера, запазете валутата на котировката за вашия език. `ACME-USD` връща 404.

`include` в upstream Beancount технически очаква име на файл, така че включването на URL е строго поведение на хоствания двигател. Той никога не се преструва, че е чист Beancount. Ето точно какво прави нашият двигател под капака:

* **Материализира канала като виртуален файл само за четене.** URL се разрешава през собствения път за разрешаване на include на двигателя — попадайки точно там, където би попаднал локален файл — така че всяка директива запазва реално местоположение на източника. Оригиналните ви байтове никога не се пренаписват. Файлът, който сте написали, си остава файлът, който сте написали.
* **Строга валидация на полезния товар.** Изтегленото тяло се валидира като *само цени*. Строго позволяваме директиви `price`, коментари и четири специфични ключа за метаданни (`price-source`, `price-kind`, `observed-at` и `provisional`). Всичко друго отхвърля цялото тяло. Няма частично поглъщане, което означава, че злонамерен канал никога не може да вмъкне транзакция в книгите ви.
* **Умно кеширане.** Каналите се кешират като неизменяема ревизия с подвижен указател. Циклите на опресняване се управляват от времеви марки, а не от изтичане на кеша, което гарантира, че прекъсване отгоре няма да заличи последната ви добра ревизия.
* **Одитируема свежест.** Свежестта се изчислява динамично при четене на регистъра (скорошна, остаряла или недостъпна) заедно с отчетеното време за наблюдение на канала. Цена, която не можете да датирате, е цена, която не можете да одитирате.
* **Строго само за четене.** Управляваните записи не могат да се редактират или изтриват (опит за това хвърля грешка, която посочва източника). Освен това не се броят към лимитите ви за директиви — не позволяваме на каналите да изяждат бюджета на регистъра ви.

Нищо от това не променя какво фундаментално означава директивата за цена в Beancount. Единствената задача на двигателя е да постави правилни, датирани и проследими цени пред зареждащия механизъм.

---

### Собствената ви цена винаги печели

Това е решаващият момент за всеки, който приема регистъра си сериозно, така че нека бъдем абсолютно ясни:

**За една и съща дата и една и съща двойка стоки (включително реципрочната ѝ), цена, която сте написали сами, винаги печели пред управлявания канал.**

Не „обикновено“ и не „само ако поставите include последен“. Това решение за засенчване се взема *преди* да бъде изградена картата на цените, което означава, че е напълно независимо от това къде се намира `include` във файла ви. Поставете го най-отгоре, най-отдолу или го разделете на три файла — ръчно написаната ви цена винаги печели.

Правилото за реципрочност е лесно за пропускане, но е жизненоважно. Канал за `AAPL-USD` е цена на AAPL в USD. Ако сте написали на ръка цена в обратната посока — USD в AAPL, същата дата — вашият запис все още побеждава канала. Същото важи и за котировката, която сте включили, било то `CNY` или `JPY`.

**Защо това правило?** Защото цена във вашия собствен файл е съзнателно решение. Може да е точното затваряне, което брокерът ви е отпечатал в извлечение, което сверявате, актуална котировка за слабо търгуван актив или конкретна цифра, която счетоводителят ви е поискал. Каналът не знае контекста ви. Система, която тихо презаписва ръчно създадена от човек цифра, престава да бъде регистър и се превръща в мнение. Каналът е там, за да запълва празнини; той не ви поправя.

---

### Цените променят оценката и нищо друго

Това следващо уверение е структурно, а не избор на политика, и най-добре се показва с реални числа. Погледнете примерния ни крипто регистър, включващ датирани партиди, стейкинг, DeFi позиции и аирдропи:

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

```beancount
2024-03-20 * "Uniswap" "Receive UNI governance token airdrop"
  Assets:Crypto:Wallet:MetaMask:UNI       50.00 UNI {12.50 USD, 2024-03-20}
  Income:Crypto:Airdrops                -625.00 USD

```

Тези $625.00 доход и базата от $12.50 за единица, прикрепена към партидата, сега са неизменни факти за 2024-03-20. Всяка директива за цена в регистъра — било то управлявана, ръчно написана или напълно липсваща — оставя и двете непокътнати.

Цените променят *пазарната стойност*; те никога не променят количества, база на разходите, парични потоци, такси или реализирани печалби. Точно затова каналът за цени е безопасен инструмент, на който да разчитате: най-лошото, което една лоша цена може да направи, е временно да изкриви стойността на дадена позиция днес. Тя никога не може да развали твърдите числа, които ще поставите в данъчната си декларация.

---

### Къде един грешен модел на цените всъщност ви подвежда

Примерният регистър за акции и ETF илюстрира по-острата версия на точно тази точка:

Той съдържа 4-към-1 сплит на акции, записан по правилния начин — като промяна в количеството, която запазва общата база, без да пипа никакви сметки за доход:

```beancount
2025-07-15 * "Broker" "NWRB 4-for-1 share split — quantity change, not income"
  Assets:Brokerage:NWRB                   -120 NWRB {41.80 USD, 2024-03-12}
  Assets:Brokerage:NWRB                    480 NWRB {10.45 USD, 2024-03-12}

```

Двете страни се равняват на $5,016.00. Пазарната стойност остава непроменена през сплита ($7,440.00 и в двата случая), а датата на придобиване във фигурните скоби оцелява — което е това, което поддържа продажбата на тези акции през 2026 г. класифицирана като дългосрочна.

Честата капан е да запишете сплит като ценово събитие вместо това, разчитайки силно на „коригирана за сплит“ ценова серия, за да излязат сметките. Това работи само докато *всяка* цена, която някога погледнете, е коригирана по абсолютно същия начин. В момента, в който в регистъра ви попадне некоригирана цифра — стар потвърдителен документ, екранна снимка или канал от трета страна, който не преизчислява историческите данни — позицията изведнъж се оценява на четири пъти реалната ѝ стойност. Още по-лошо: броят акции в регистъра вече не съвпада с извлечението на брокера ви, което означава, че проверките на баланса в края на годината тихо ще се провалят.

Това е истинският аргумент в полза на разчитането на канал за цени с деклариран източник, деклариран вид и видимо време за наблюдение. Не става дума само за удобство; става дума за това да знаете точно каква математическа конвенция използват внесените ви числа.

*(Кратка бележка за вградените елементи: хостваният преглед на регистъра изобразява салдата по сметките по разход и в момента не предлага контроли за оценка на страницата. Регистрите по-горе имат за цел да покажат лежащата в основата механика — партидите, сплита, продажбите. И двата са публични и можете да ги клонирате и стартирате локално.)*

---

### Какво още не е тук

Вярваме, че един changelog е по-лош от безполезен, ако дава прекалено големи обещания. Затова ето нечупената истина за това какво още *не* сме изградили, без прикачени срокове:

* **Автентикацията е задължителна.** Анонимните заявки към `https://beancount.io/prices/<ALIAS>` ще ви препратят към страница за вход.
* **Няма локална CLI поддръжка.** Локалният CLI `bea` чете файлове от диска, което означава, че include на URL ще се провали локално като несъвпадащ файлов шаблон. Добавянето на поддръжка на зареждане в CLI е в плана ни.
* **Няма API повърхност.** В момента нямаме REST, GraphQL или MCP поле за управлявани цени.
* **Няма UI табло.** Все още няма екран „свържи канал“ и няма етикет за свежест в UI. (Данните за свежест, които нашият двигател изчислява, в момента няма къде да бъдат показани).
* **Няма snapshot-и, експорти или крайни точки за ръчно опресняване.**

Това, което пуснахме днес, е строго слоят на двигателя: разрешаване на include, валидация, кеширане на ревизии, правила за приоритет и изчисляване на свежест. Това е основополагащата инфраструктура, върху която всичко останало трябва да стъпи, което е точно причината да я изградим първо.

---

### Къде да погледнете след това

И двата регистъра, вградени по-горе, са част от нашата галерия с примери — шест напълно разработени модела, които можете да клонирате и стартирате локално. (И двата умишлено се доставят със статични, вписани във версията файлове с цени, което гарантира, че клонинг, направен две години по-късно, ще произведе точно същия отчет като днес). Всичко останало, което пускаме, се появява директно в нашия changelog.

Ако сте напълно доволни да поддържате цените актуални със собствен изтеглящ механизъм, продължете с него. Той остава най-добрият отговор за строго локален регистър. Собствената [документация за изтегляне на цени](https://beancount.github.io/docs/fetching_prices_in_beancount/) на Beancount и поддържаният инструмент `beanprice` са най-добрите места за начало.

### Пазете скучната част скучна

Цените си заслужават автоматизирането именно защото са единствената част от регистъра с чист текст, която се разваля с времето. Beancount.io е изграден да ви даде счетоводство с чист текст, което остава *ваше* — одитируемо, контролирано с версии и никога пренаписано зад гърба ви. Това беше базовият стандарт, който един управляван канал трябваше да покрие, преди да бяхме готови да го пуснем.

Започнете безплатно и пазете книгите си във файлове, които наистина можете да четете.
