Nordlet

← Блог

Разработка бухгалтерского API, способного пройти аудит

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

Nordlet Team · · 10 мин. чтения

Бухгалтерский API, который возвращает код 200 OK при создании платежа, не говорит практически ни о чем. Он не подтверждает, что проводка была занесена в регистр, что у инициатора было на это право, что сумма прошла проверку и что кто-либо из уполномоченных лиц одобрил операцию. Для бизнеса в Нидерландах, где налоговые органы требуют, чтобы финансовая отчетность поддавалась восстановлению и хранилась в течение семи лет, этот разрыв между «запрос выполнен успешно» и «книги учета верны» становится причиной проваленных аудитов.

Готовность к аудиту (audit-ready) - это цель операционного проектирования, а не сертификат. Она означает, что API сохраняет цельную цепочку: аутентифицированный субъект - авторизованное действие - проверенное изменение состояния - одобрение - результат в регистре - защищенные от подделки доказательства. Все, о чем пойдет речь ниже, направлено на осознанное построение этой цепи, а не на надежду, что аутентификация и TLS решат все проблемы.

Что делает бухгалтерский API готовым к аудиту

Аудитору, восстанавливающему цепочку транзакции, необходимо ответить на конкретную последовательность вопросов. Кто ее инициировал? Было ли у него на это разрешение? Прошло ли изменение бухгалтерскую валидацию? Кто его одобрил? Что именно зафиксировал регистр? Можно ли изменить эту запись задним числом без оставления следов?

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

Элементы контроля, которые закрывают эти пробелы, делятся на несколько групп: явное бухгалтерское состояние, многоуровневая авторизация, ограниченная аутентификация (scoped authentication), идемпотентность операций записи, серверная валидация, разделение обязанностей и защита логов от несанкционированных изменений. Они подкрепляют друг друга. Слабая авторизация подрывает надежность надежного аудиторского лога, поскольку вы больше не можете быть уверены, что зарегистрированный субъект имел хоть какое-то отношение к выполнению действия.

Моделируйте бухгалтерские состояния перед проектированием эндпоинтов

Самая распространенная ошибка при проектировании - рассматривать каждую финансовую запись как свободно редактируемый объект с операциями create, read, update, delete. Бухгалтерия так не работает, и аудитор сразу заметит, если проведенная проводка журнала может быть незаметно перезаписана.

Каждый ресурс, имеющий финансовое значение, должен проходить через явный автомат состояний (state machine). Журнал проволок или платеж обычно проходит следующие этапы:

draft (черновик) → submitted (отправлено) → approved (одобрено) → posted (проведено) → settled (расчет завершен)

Исправления не отменяют этот путь назад. Неправильная проведенная запись получает связанную сторнирующую проводку (reversal) или корректировку. Оригинал остается нетронутым.

Рабочий набор правил выглядит следующим образом:

  • Черновики могут редактироваться пользователями с соответствующими правами.
  • Отправленные записи могут редактироваться только ролями с определенными разрешениями либо возвращаться в статус черновика.
  • Одобренные записи требуют контролируемой правки и повторного одобрения.
  • Проведенные записи нельзя перезаписывать или удалять, их можно только сторнировать или корректировать.
  • Изменения в закрытом периоде требуют повышенных полномочий, указания причины и создания события аудита.

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

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

Авторизуйте каждый запрос, а не только аутентифицируйте его

Аутентификация доказывает личность вызывающей стороны. Она ничего не говорит о том, имеет ли этот вызывающий субъект право обращаться к конкретному счету-фактуре, журналу или юридическому лицу. Проект OWASP API Security ставит проблему нарушения авторизации на уровне объектов (broken object-level authorization) на первое место в списке рисков именно потому, что API раскрывают идентификаторы объектов, упрощающие межтенантный доступ при отсутствии проверок.

Каждый запрос к финансовому API должен авторизовываться на основе совокупности факторов, а не только токена:

  • аутентифицированный субъект;
  • клиентское приложение или сервисный аккаунт;
  • тенант (организация);
  • юридическое лицо;
  • идентификатор ресурса;
  • запрашиваемая операция;
  • текущее состояние ресурса;
  • сумма или порог транзакции.

Два практических правила важнее остальных. Первое: выводите контекст тенанта и пользователя из аутентифицированной идентичности и отклоняйте любые утверждения (claims) о тенанте или роли, переданные клиентом, если они ей противоречат. Вызывающая сторона никогда не должна иметь возможность самостоятельно заявлять, от имени какой компании она действует. Второе: используйте принцип запрета по умолчанию (deny-by-default). Если ни одна политика явно не разрешает действие, оно отклоняется.

Тестируйте оба направления: горизонтальный доступ, когда один тенант получает доступ к данным другого, и вертикальный доступ, когда обычный пользователь получает доступ к функциям одобрения, проведения или экспорта. И то, и другое встречается часто и приводит к катастрофическим последствиям для бухгалтерских данных.

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

Ограничивайте токены бизнес-возможностями, а не CRUD-глаголами

Для делегированного доступа используйте современные рекомендации по безопасности OAuth 2.0 вместо многоразовых паролей или широких статических ключей API. RFC 9700 является актуальной лучшей практикой (Best Current Practice) и устанавливает четкие требования к клиентам и серверам авторизации: проверенные URI перенаправления, использование PKCE там, где это применимо, проверка издателя и аудитории, короткое время жизни токенов доступа и ротация токенов обновления (refresh-token rotation) с их отзывом.

Выбор областей видимости (scopes) наглядно демонстрирует специфику бухгалтерского подхода. Общие скопы вроде read и write практически бесполезны для разделения обязанностей. Скопы должны соотноситься с конкретными возможностями:

  • journal:create и journal:approve должны быть разными скопами.
  • Создание платежного поручения не дает разрешения на его выпуск.
  • Разрешение на экспорт отделено от разрешения на чтение, поскольку массовый экспорт представляет собой путь утечки данных.

Четко определяйте, где именно находится ваш продукт на этой шкале. Ключи API Nordlet поддерживают скопы на уровне модулей, такие как sales:read и sales:write, проверяемые при каждом действии. Это разграничивает модули и операции чтения/записи, но не разделяет создание и одобрение; там, где вам требуется более тонкая настройка, обеспечивайте ее в рамках собственного сервиса перед вызовом API.

Для дорогостоящих операций стоит оценить применимость профиля безопасности FAPI 2.0. Он разработан для API, защищающих конфиденциальные финансовые данные, и предоставляет более сильные гарантии, чем базовый OAuth. Большинству интеграций для малого и среднего бизнеса этот профиль в полном объеме не потребуется, но процессы проведения платежей и подключения банков - это именно те области, где о нем стоит задуматься.

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

Сделайте финансовые операции записи идемпотентными

Сети падают посреди запроса. Клиент отправляет платежное поручение, соединение обрывается до получения ответа, и клиент повторяет запрос. Без защиты у вас появится два платежа.

Ключи идемпотентности (idempotency keys) решают эту проблему. Клиент отправляет уникальный ключ с каждым запросом на запись; сервер сохраняет ключ и результат его выполнения. Повторный запрос с тем же ключом возвращает исходный результат вместо создания второй записи. Nordlet принимает заголовок Idempotency-Key для каждого мутирующего вызова, воспроизводя сохраненный ответ при повторении запроса с тем же телом и отклоняя тот же ключ, если полезная нагрузка была изменена. Любой бухгалтерский API, упускающий эту функцию, в конечном итоге породит дубликаты проводок, которые кому-то придется вручную распутывать.

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

Защищенные от подделки аудиторские логи и нидерландские сроки хранения

Журнал аудита - это слой доказательств, и к нему предъявляются требования, отличные от требований к обычным бизнес-данным. В нем должны фиксироваться решение об авторизации, версия политики, субъект, объект, операция, предыдущее и новое состояние, а также код причины, но ни в коем случае не секреты или полные платежные данные.

Критически важным свойством является защита от подделки (tamper-evidence). Если администратор может незаметно отредактировать или удалить записи аудита, такой лог ничего не доказывает. Этим требованиям отвечают хранилища «только для добавления» (append-only), криптографические цепочки или неизменяемое хранение с однократной записью. Суть в том, что любое вмешательство должно быть обнаруживаемым.

Сроки хранения (retention) заслуживают отдельной политики, независимой от удаления бизнес-данных. В Нидерландах общий срок хранения административных документов составляет семь лет, а для документов по недвижимости - десять. Ваши стандартные рабочие процессы удаления данных и соблюдения GDPR не должны уничтожать записи или доказательства аудита, на которые распространяются правила юридического хранения. Определите правила юридического удержания (legal hold), архивирования и удаления доказательств независимо от остального функционала и сопоставьте их с юрисдикциями, в которых вы работаете.

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

Защита периметра: вебхуки, экспорт и интеграции

Основной API обычно является наиболее защищенной частью системы. Утечки происходят на периметре.

Вебхуки несут в себе риск поддельных запросов. Событие вроде sale_invoice.paid должно быть подписано, чтобы получатель мог проверить его источник. Получатели должны обрабатывать доставку по принципу «хотя бы один раз» (at-least-once) и использовать идентификатор события для дедупликации. Nordlet подписывает каждую доставку вебхука HMAC-подписью по «сырому» телу запроса и повторяет неудачные доставки с экспоненциальной задержкой, поэтому получатель должен проверять подпись и выполнять дедупликацию по ID события, не полагаясь на гарантию доставки ровно один раз (exactly-once).

Экспорт данных - это путь к масштабной утечке. Экспорт отчетов в форматах XLSX, PDF или JSON выгружает большие объемы финансовых данных за одну операцию, поэтому он требует собственных разрешений, лимитов частоты запросов (rate limits) и логирования аудита. Сторонние интеграции, которые вы подключаете, должны рассматриваться как ненадежные источники и проходить такую же валидацию, как и прямые запросы клиентов.

Чек-лист готовности к аудиту для нидерландского бухгалтерского API

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

  • Явный автомат состояний для каждого финансового ресурса; проведенные записи нельзя перезаписывать.
  • Авторизация на уровне объектов и юридических лиц для каждого запроса с правилом запрета по умолчанию.
  • Контекст тенанта и роли, извлекаемый из токена, а не из клиентских утверждений.
  • OAuth 2.0 согласно RFC 9700; скопы на основе возможностей; разделение создания и одобрения.
  • Разделение обязанностей, закрепленное на уровне ролей, а не только на бумаге.
  • Ключи идемпотентности для всех финансовых операций записи.
  • Серверная проверка бухгалтерии и НДС перед изменением состояний.
  • Защищенный от подделки лог аудита «только для добавления» с кодами причин.
  • Правила хранения и юридического удержания, привязанные к нидерландским срокам (семь лет, десять для недвижимости).
  • Блокировка закрытых месяцев.
  • Подписанные вебхуки с дедупликацией; логируемый экспорт с ограниченным доступом и rate limits.

С чего мы начали бы в первую очередь

Если бы нам пришлось внедрять бухгалтерию в нидерландскую платформу завтра, мы бы начали с модели состояний и авторизации на уровне объектов до написания хотя бы одного бизнес-эндпоинта. Эти два решения определяют все последующие этапы, а внедрение их задним числом в систему, где записи регистра рассматривались как редактируемые строки - задача исключительно сложная. Идемпотентность и аудит-лог идут следом, поскольку их дешево добавлять на раннем этапе и дорого внедрять после потока реальных данных.

Все остальное - токены со скопами, подписанные вебхуки, блокировка периодов - выстраивается значительно проще, когда фундамент надежен. Любой из этих компонентов можно протестировать на песочнице (sandbox) до того, как они коснутся производственных данных.

FAQ

Означает ли наличие готового к аудиту API, что весь бизнес соответствует требованиям?

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

Как долго должны храниться бухгалтерские документы в Нидерландах?

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

Достаточно ли статического ключа API для финансовой интеграции?

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

Почему идемпотентность так важна именно для бухгалтерии?

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

Дополнительное чтение