Какво представлява счетоводният API? Наръчник на достъпен език за създатели на софтуерни платформи

Определение на счетоводния API на достъпен език, разликата му от данъчния API или API за плащания и какво да проверите, преди да интегрирате такъв.

Счетоводният API е интерфейс, който позволява на една програма да води счетоводството на друга. Вашият софтуер изпраща финансово събитие през HTTP. API-ят преобразува това събитие в балансирани двустранни счетоводни статии (journal entries) спрямо сметкоплан (chart of accounts), съхранява ги така, че да не могат да бъдат незабелязано променени, прилага съответното данъчно третиране и ви връща справки, документи и експорти през същия интерфейс.

Това определение върши по-голямата част от работата. Всичко останало в тази статия е следствие от него.

Версията в едно изречение

Счетоводният API приема финансови събития от вашето приложение, преобразува всяко от тях в балансирана счетоводна статия, съхранява я неизменно заедно с данъчното ѝ третиране и придружаващите доказателства, и излага получената главна книга (ledger), документите и справките като програмни крайни точки (endpoints).

Ако даден продукт се нарича счетоводен API, но не генерира счетоводни статии, той е нещо друго с хубаво име. Това не е непременно лошо. Просто означава, че няма да свърши работата, за която се каните да го използвате.

Какво НЕ е счетоводният API

Четири съседни продуктови категории често се бъркат със счетоводните API-и, обикновено в напреднал етап на даден проект.

Категория	Какво прави	Какво НЕ прави
API за изчисляване на данъци (Tax calculation API)	Връща правилната ставка или данъчна сума за транзакция	Не води счетоводството ви и не съхранява доказателствата зад решението за срока на съхранение
API за плащания (Payments API)	Превежда пари между страните и докладва за тези движения	Не отчита спечелената комисиона, дължимото ДДС или задължението към продавач между плащането и изплащането
Унифициран или агрегиращ API (Unified or aggregator API)	Чете и записва данни в съществуващия счетоводен софтуер на вашия клиент	Не действа като основна система за отчитане (system of record); вашите счетоводни книги се намират в инструмента, който всеки клиент вече използва
API за справки или бизнес разузнаване (Reporting or BI API)	Чете числа от съществуваща главна книга и ги визуализира	Не създава статиите, от които са изведени тези числа

Всяко от тези решения има реални приложения. Една платформа, която трябва да бъде основна система за отчитане, се нуждае от счетоводен API под себе си, а не вместо него.

Петте неща, които счетоводният API трябва да прави

1. Записва балансирани статии. Всяко събитие се превръща в дебити и кредити, които се сумират до една и съща стойност. Когато купувач плати 100 евро на маркетплейс (marketplace), който взема 15 евро комисиона, статията дебитира разчетна сметка (clearing account) със 100 евро, кредитира задължение към доставчик (seller payable) с 85 евро и кредитира приходи от комисиони с 15 евро. Това не е счетоводен ритуал. Това е структурна проверка, която улавя цели класове грешки при интеграцията, преди те да стигнат до отчет.

2. Пази история. Публикуваната статия (posted entry) не се редактира. Една грешка се коригира чрез сторно (reversal) плюс коригираща статия, като и двете са обвързани с оригинала. Затворените месеци се заключват, така че нищо ново да не може да бъде датирано в тях.

3. Изчиства данъчните казуси. При търговия в рамките на ЕС това означава място на изпълнение (place of supply), обратно начисляване (reverse charge), валидиране на ДДС номера срещу официалния регистър и доказателствата, обосновали решението - всичко това се съхранява заедно с транзакцията, вместо да се изхвърля след изчислението.

4. Извършва съвместяване (reconciliation) срещу външни парични потоци. Счетоводни книги, които никога не се засичат с банково извлечение, са просто предположение. API-ят трябва да приема извлечения или плащания от доставчици (provider settlements) и да ги съпоставя с това, което е било зачетено.

5. Експортира данни. Справки, документи и одитни файлове във формати, които човешкото счетоводство и приходната администрация приема.

Продукт, който прави първите три неща, но не и последните две, все пак ще остави някой човек да върши работа с електронни таблици всеки месец.

Как изглежда едно извикване в действителност

Механиката е по-опростена от счетоводството. В API-я на Nordlet всяка операция е POST заявка в стил RPC с предсказуема структура:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

Вие създавате фактура за продажба и след това я издавате. Издаването е моментът, в който се случва счетоводното отчитане: документът получава своя пореден номер без пропуски (gapless number), балансираната счетоводна статия се публикува и редовете за ДДС се записват заедно с нея. Вашата платформа никога не съставя дебити и кредити на ръка.

Три детайла в този код имат по-голямо значение от името на крайната точка:

Обхватът (scope) на ключа. Ключът носи разрешения като sales:write, така че интеграцията да получава само достъпа, от който се нуждае.
Ключът за иденпотентност (idempotency key). Повторете същата заявка със същия полезен товар (payload) и ще получите съхранения отговор обратно вместо втора фактура. Изпратете същия ключ с различен полезен товар и заявката ще бъде отхвърлена с грешка idempotency_key_reuse, вместо да бъде тихо приета.
Парите като текстови низове (strings). Сумите са десетични низове, а не числа с плаваща запетая (floats), тъй като плаващата запетая губи стотинки по начини, които се проявяват в края на годината.

Къде се намира той във вашата архитектура

Приложението ви остава фронтенд (frontend) частта и източникът на бизнес събития. Счетоводният API се превръща във финансова система за отчитане зад него. Процесът обикновено изглежда така:

Нещо се случва във вашия продукт: поръчка, възстановяване на сума, изплащане, подновяване на абонамент.
Вашият бекенд (backend) извиква счетоводния API със събитието и ключ за иденпотентност.
API-ят публикува счетоводната статия, прилага ДДС и връща идентификатори, които записвате към собствените си записи.
Уебхук (webhook) като sale_invoice.paid уведомява вашата система, когато състоянието се промени, така че да реагирате на събития, вместо да ги проверявате периодично (polling).
Банковите транзакции пристигат чрез банков канал или импорт на извлечение и се съпоставят със зачетените документи.
В края на периода от същите данни се генерират справки и данъчни регистри, а затвореният месец се заключва.

Нищо в този списък не изисква човек да отваря счетоводен софтуер. В това е и смисълът на тази категория.

Как се сравнява с алтернативите

Подход	Усилие за започване	Одитна позиция	Мащабира се с обема на транзакциите
Електронни таблици и ръчно въвеждане	Най-ниско	Слаба; историята може да се редактира	Не
Счетоводен софтуер плюс CSV експорти	Ниско	Зависи изцяло от дисциплината	Слабо; някой трябва да импортира файлове
Агрегиращ API към счетоводството на всеки клиент	Средно	Наследява каквото прави инструментът на клиента	Да, но никога не притежавате записа
Вграден счетоводен API (Embedded accounting API)	Средно	Силна, ако главната книга е неизменна и периодите се заключват	Да
Изграждане на собствена главна книга	Най-високо	Силна само ако изградите и контролите	Да, и я поддържате завинаги

Изграждането на собствено решение е разумен избор за някои екипи. То е разгледано по-подробно в нашето ръководство за изграждане спрямо закупуване за маркетплейси.

Какво да проверите, преди да интегрирате такъв API

Салдото изведено (derived) ли е, или съхранено? Попитите дали салдото на продавач е заявка върху счетоводни редове, или колона, която някой актуализира. Само едното от двете издържа на одит.
Какво се случва при повторен опит (retry)? Изпратете една и съща заявка два пъти и пребройте статиите.
Можете ли да редактирате публикувана статия? Отговорът трябва да е „не“, придружен от документиран път за корекция.
Заключеният период наистина ли отхвърля публикуването? Опитайте го в тестова среда (sandbox). Nordlet връща 409 за статия с дата вътре в заключен период.
Как са представени парите? Десетични низове или целочислени малки единици (minor units). Никога плаваща запетая.
Какво има в одиторския запис (audit record)? Субект (actor), действие, обект (entity) и самата промяна, достъпни за заявки, вместо да са скрити в лог файлове (log files).
Какви са лимитите на заявките (rate limits)? Nordlet позволява 300 заявки в минута на API ключ и докладва оставащия ви ресурс в хедърите на отговора. Каквото и да е числото, научете го, преди да проектирате синхронизацията си.
Как си извличате данните? Справки, документи и журнали във формати, които можете да предадете на счетоводител.

Всяко от тези неща може да бъде тествано за следобед срещу тестова компания (sandbox company). Списъците с функции на доставчиците не са доказателство; възпроизводимият тест е.

FAQ

Счетоводният API същото ли е като счетоводния софтуер?

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

Все още ли ми трябва счетоводител, ако използвам такъв API?

Да. Един API автоматизира записването, изчисляването и отчитането. Той не взема експертни решения относно класификацията, провизиите или начина, по който трябва да се третира конкретен договор, и в повечето държави не подписва и не подава годишните ви финансови отчети.

Мога ли да използвам счетоводен API, без да разбирам двустранното счетоводство?

Отчасти. Добрият API изгражда счетоводните статии вместо вас от бизнес документ като фактура. Все пак трябва да разбирате какво означават сметките, когато четете отчет или обяснявате салдо на одитор.

каква е разликата между счетоводен API и API за главна книга (ledger API)?

API-ят за главна книга записва балансирани движения между сметки. Счетоводният API прави това и добавя регулаторния слой отгоре: документи с правна нумерация, третиране по ДДС, данъчни регистри, дълготрайни активи, приключване на период и справките, които съответната юрисдикция очаква. Всеки счетоводен API съдържа главна книга, но не всяка главна книга е счетоводна система.

Колко време отнема интеграцията?

За първоначален работен процес - създаване на клиент, издаване на фактура, получаване на плащане, преглед на счетоводната статия - планирайте дни, а не седмици, като използвате типизиран SDK и тестова среда. Производствената интеграция, обхващаща възстановявания на суми, корекции, валути, съвместяване и приключване на период, е по-мащабна задача, като честната оценка зависи от това колко от тези казуси всъщност генерира вашият продукт.