Что такое бухгалтерский API? Руководство на простом языке для разработчиков платформ

Простое определение бухгалтерского API, его отличия от налогового или платежного API, а также чек-лист перед началом интеграции.

Бухгалтерский API — это интерфейс, который позволяет одной программе вести учет для другой программы. Ваше ПО отправляет финансовое событие по протоколу HTTP. API преобразует это событие в сбалансированные проводки методом двойной записи (double-entry) на счетах плана счетов (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 отчетности или BI (Reporting or BI API)	Читает показатели из существующей главной книги и визуализирует их	Не создает проводки, на основе которых получены эти показатели

У каждого из этих решений есть свое реальное применение. Платформе, которой необходимо быть системой учета, требуется именно бухгалтерский API в качестве основы, а не замена ему.

Пять задач, которые должен решать бухгалтерский API

1. Регистрировать сбалансированные проводки. каждое событие превращается в дебет и кредит, которые в сумме дают одинаковое значение. Когда покупатель платит €100 на маркетплейсе, который удерживает комиссию €15, проводка оформляется по дебету транзитного счета на €100, по кредиту счета обязательств перед продавцом на €85 и по кредиту доходов от комиссии на €15. Это не бухгалтерская формальность. Это структурная проверка, которая отсекает целые классы интеграционных ошибок до того, как они попадут в отчет.

2. Сохранять историю. Проведенный документ не редактируется. Ошибка исправляется сторнированием (reversal) и исправленной проводкой, причем обе они связаны с исходной. Закрытые периоды блокируются, чтобы в них нельзя было задним числом провести новые операции.

3. Рассчитывать налоги. В торговле внутри ЕС это означает определение места реализации (place of supply), применение обратного начисления (reverse charge), проверку регистрационных номеров плательщика НДС по официальному реестру, а также сохранение обосновывающих документов прямо рядом с транзакцией вместо их удаления после расчета.

4. Выполнять сверку с внешними деньгами. Книги, которые никогда не сопоставляются с банковской выпиской, — это лишь предположение. API должен принимать выписки или отчеты о выплатах от платежных провайдеров и сопоставлять их с тем, что было записано.

5. Экспортировать данные. Отчеты, документы и аудиторские файлы в форматах, которые принимают профессиональный бухгалтер и налоговая инспекция.

Продукт, который выполняет первые три задачи, но не справляется с последними двумя, по-прежнему заставляет человека каждый месяц работать в электронных таблицах.

Как выглядит реальный вызов

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

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

Вы создаете счет на оплату, а затем проводите его. Проведение — это момент, когда совершается бухгалтерская операция: документ получает сквозной номер, формируется сбалансированная проводка, а вместе с ней фиксируются строки НДС. Ваша платформа никогда не собирает дебет и кредит вручную.

Три детали в этом фрагменте кода важнее, чем название эндпоинта:

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

Место в архитектуре приложения

Ваше приложение остается фронтендом и источником бизнес-событий. Бухгалтерский API становится финансовой системой учета за ним. Типичный сценарий работы выглядит следующим образом:

В вашем продукте происходит событие: заказ, возврат, выплата, продление подписки.
Ваш бэкенд вызывает бухгалтерский API, передавая событие и ключ идемпотентности.
API создает проводку, применяет НДС и возвращает идентификаторы, которые вы сохраняете в своей базе данных.
Вебхук (webhook), например sale_invoice.paid, сообщает вашей системе об изменении статуса, позволяя реагировать на события вместо опроса сервера.
Банковские транзакции поступают через банковскую выписку или импорт файлов и сопоставляются с записанными документами.
По окончании периода на основе тех же данных формируются отчеты и налоговые регистры, а закрытый месяц блокируется.

Ни один пункт из этого списка не требует от человека открывать бухгалтерскую программу. В этом и заключается суть данной категории продуктов.

Сравнение с альтернативами

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

Самостоятельная разработка — вполне осознанный выбор для некоторых команд. Подробнее об этом рассказано в нашем руководстве по выбору между собственной разработкой и покупкой для маркетплейсов.

Чек-лист перед началом интеграции

Баланс вычисляется динамически или сохраняется в поле? Уточните, является ли баланс продавца результатом запроса по строкам проводок или значением в колонке, которое кто-то обновляет. Только один из этих вариантов выдержит аудиторскую проверку.
Что происходит при повторной отправке запроса (retry)? Отправьте один и тот же запрос дважды и посчитайте количество проводок.
Можно ли отредактировать уже проведенную операцию? Ответ должен быть отрицательным, с наличием задокументированного механизма исправления.
Действительно ли заблокированный период отклоняет проводку? Проверьте это в песочнице (sandbox). Nordlet возвращает статус 409 для проводок с датой внутри заблокированного периода.
Как представлены денежные суммы? В виде строковых десятичных чисел или минимальных единиц валюты (например, в центах). Никаких чисел с плавающей запятой.
Что входит в аудиторский след (audit record)? Инициатор действия, само действие, объект и внесенные изменения. Данные должны быть доступны для запросов, а не затеряны в лог-файлах.
Каковы лимиты запросов (rate limits)? Nordlet разрешает 300 запросов в минуту на один API-ключ и сообщает об оставшемся лимите в заголовках ответа. Каким бы ни было это число, узнайте его до того, как начнете проектировать синхронизацию.
Как забрать свои данные обратно? Отчеты, документы и журналы проводок должны быть доступны в форматах, которые можно передать бухгалтеру.

Каждый из этих пунктов можно протестировать за полдня в компании-песочнице. Списки функций на сайтах вендоров — не доказательство, а воспроизводимый тест — доказательство.

FAQ

Является ли бухгалтерский API тем же самым, что и бухгалтерское программное обеспечение?

Это бухгалтерское ПО с измененным интерфейсом. Традиционные бухгалтерские программы предоставляют человеку прямой доступ к главной книге, а бухгалтерский API предоставляет этот доступ вашему коду. Базовые принципы, метод двойной записи и отчетность остаются прежними.

Нужен ли мне бухгалтер, если я использую такой API?

Да. API автоматизирует регистрацию, расчеты и формирование отчетов. Он не принимает экспертных решений по поводу классификации расходов, резервов или того, как следует трактовать конкретный контракт, а в большинстве стран он не подписывает и не сдает вашу регламентированную отчетность.

Можно ли использовать бухгалтерский API, не понимая метод двойной записи?

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

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

API главной книги фиксирует сбалансированные движения средств между счетами. Бухгалтерский API делает то же самое, но добавляет сверху законодательный слой: документы с юридической нумерацией, учет НДС, налоговые регистры, основные средства, закрытие периодов и отчеты, требуемые в конкретной юрисдикции. Каждый бухгалтерский API содержит в себе главную книгу, но не каждая главная книга является бухгалтерской системой.

Сколько времени занимает интеграция?

Для реализации базового рабочего сценария — создания клиента, выставления счета, получения оплаты и просмотра проводки — при наличии типизированного SDK и песочницы планируйте потратить дни, а не недели. Производственная интеграция, охватывающая возвраты, исправления, работу с несколькими валютами, сверку и закрытие периодов, представляет собой более масштабную задачу, и честная оценка сроков зависит от того, сколько именно таких сценариев генерирует ваш продукт.