Открытые программные интерфейсы
| Статус | Рекомендательный документ |
| Область | Прикладные стандарты получения информации о банковских счетах Пользователя |
| Категории пользователей | Физические лица, юридические лица |
| Характер положений | Добровольный ориентир. Не заменяет стандарты Банка России |
Настоящий документ содержит описание ключевых кейсов и рекомендаций по реализации методов получения информации о банковских счетах Пользователя в рамках комплекса стандартов Банка России «Открытые программные интерфейсы».
Документ разработан с целью обеспечения единообразного подхода к реализации изменений в прикладных стандартах, повышения эффективности обмена данными между Поставщиками услуг (ПУ) и Сторонними поставщиками услуг (СПУ), а также снижения рисков и нагрузки на информационные системы участников среды Открытых API.
В условиях, когда стандарты Открытых API определяют базовые технические требования и форматы данных, настоящий документ выполняет роль инструмента гармонизации взаимодействия между участниками. Он аккумулирует технологический опыт участников среды Открытых API для решения инфраструктурных вызовов, которые не могут быть жёстко регламентированы стандартом. Рекомендации разделены по категориям пользователей — физических и юридических лиц.
Настоящий документ предназначен для:
a. участников взаимодействия, осуществляющих обмен информацией о банковских счетах физических лиц и юридических лиц, а также связанной с ними информацией;
b. разработчиков информационного и программного обеспечения.
Документ применяется совместно с комплексом стандартов Банка России «Открытые программные интерфейсы», в том числе с документами:
Положения документа следует читать с учётом принципов архитектуры {ОАПИ-А1}–{ОАПИ-А6}, принципов пользовательского опыта и информационной безопасности «Общих положений». Рекомендации не должны нарушать обратную совместимость действующих интеграций без явного решения о версии (см. {ОАПИ-А6}).
Настоящий документ определяет практические рекомендации по доработке методов API в рамках стандартов «Получение информации о банковских счетах Пользователя».
Основными целями документа являются:
Положения настоящего документа носят рекомендательный характер и представляют собой добровольно принимаемый участниками ориентир при проектировании, доработке и актуализации следующих стандартов:
Документ применяется совместно с комплексом стандартов Банка России «Открытые программные интерфейсы».
Если рекомендация меняет наблюдаемое поведение уже опубликованного метода (порядок элементов, состав выборки, код ответа), её включение в прикладной стандарт оценивается по правилам версионирования {ОАПИ-А6}: параметр или новый default без ломки контракта — кандидат в минорную версию; несовместимое изменение default — кандидат в мажорную.
Таблица 1 — Ключевые рекомендации по методам получения информации о счетах физических лиц
| Суть изменения | Техническая реализация | Цель | Область применения (метод API) |
|---|---|---|---|
| Декрементная сортировка списка операций. Операции возвращаются в порядке убывания даты, используемой для упорядочивания (от новых к старым), со стабильным вторичным ключом. | Рекомендуемый ключ сортировки — дата последнего изменения операции, если такое поле есть в модели. Поле valueDateTime использовать только как допустимый суррогат при отсутствии поля изменения записи: это дата валютирования, а не дата обновления статуса. Стабильный вторичный ключ — transactionId. Default-порядок фиксируется в спецификации. |
СПУ получает более новые (и при наличии поля изменения — недавно обновлённые) операции вверху списка, что упрощает валидацию, сверку и отображение в интерфейсе. Пагинация не «плывёт» при одинаковом времени. | GET /transactions GET /accounts/{accountId}/transactions |
| Инкрементальный обмен данными. ПУ возвращает СПУ только операции, созданные или изменённые после курсора последнего успешного запроса, вместо полного набора. | Внешний контракт — параметризованный запрос (курсор или fromLastUpdateDateTime / эквивалент), а не скрытое состояние «для каждого СПУ». Маркерная таблица на стороне ПУ допустима как внутренняя оптимизация. Обязателен механизм полного набора данных (full sync). Маркер/курсор сдвигается только после успешной отдачи ответа. |
Снижение нагрузки на системы ПУ и СПУ, уменьшение объёма передаваемых данных, экономия сетевых ресурсов, сохранение stateless-контракта REST {ОАПИ-А1}. | GET /transactions GET /accounts/{accountId}/transactions в перспективе — другие методы с объёмной историей |
В методах получения операций (GET /transactions, GET /accounts/{accountId}/transactions) ПУ рекомендуется возвращать операции в порядке убывания даты упорядочивания (от новых к старым).
Рекомендации по реализации на стороне ПУ
lastUpdateDateTime / statusUpdateDateTime), если он есть или будет добавлен в модель.valueDateTime — дата валютирования. Его можно использовать как ключ сортировки только если в модели нет даты изменения записи. В этом случае не следует утверждать, что наверх списка гарантированно поднимаются операции с обновлённым статусом: статус может измениться при прежнем valueDateTime.transactionId (DESC или ASC — единообразно у всех ПУ и явно в спецификации).Зачем это нужно. СПУ проще показывать свежие операции и быстрее находить недавно изменившиеся статусы (при наличии корректного ключа), не перебирая всю страницу.
При повторных запросах объёмных выборок (история операций за длительный период) СПУ часто запрашивает один и тот же массив целиком, даже если большая часть данных уже получена и не изменилась. Это создаёт избыточную нагрузку на ПУ и СПУ при росте числа клиентов и частоты запросов.
Рекомендуется отдавать только операции, которые созданы или изменены после курсора последнего успешного запроса данного клиента, и отдельно поддерживать получение полного набора.
Внешний контракт (рекомендуемый, соответствует {ОАПИ-А1}, {ОАПИ-А2})
fromLastUpdateDateTime, page[after] либо согласованный эквивалент из прикладного стандарта).Маркерные таблицы на стороне ПУ
Алгоритм «ПУ хранит маркер для каждого СПУ и сам отсекает уже отданное» допустим только как внутренняя реализация за тем же внешним контрактом. Выносить персональный маркер СПУ в нормативное поведение метода не рекомендуется:
Если ПУ всё же ведёт внутренний маркер:
Full sync — обязательное парное требование. Без него инкремент непригоден: ротация журнала на стороне ПУ, смена контура СПУ, расхождение курсора и разбор инцидентов требуют полной выгрузки. Конкретный параметр (sync=full, отсутствие курсора и т.п.) согласовывается в рабочей группе и затем фиксируется в спецификации.
Совместимость с пагинацией. Инкремент и постраничная выдача применяются совместно: курсор задаёт множество изменений, пагинация дробит это множество. Нельзя сдвигать watermark по факту «первая страница отдана», если клиент не подтвердил получение остальных страниц.
Требуется детальная проработка с участниками: имя параметра курсора, поле, по которому он считается, поведение при одинаковых временных метках, коды/признаки пустого инкремента и full sync.
Таблица 2 — Ключевые рекомендации по методам получения информации о счетах юридических лиц
| Суть изменения | Техническая реализация | Цель | Область применения (метод API) |
|---|---|---|---|
Разделение логики ответа GET согласия в зависимости от состояния записи согласия, а не только от expirationDateTime. |
Если согласие есть в оперативной базе — HTTP 200 OK (в том числе при истекшем expirationDateTime и при статусе «Отозвано»). Если согласие архивировано или не существует — HTTP 403 Forbidden и код RU.CBR.Authenticate.InvalidConsent. Различие «архивировано» / «никогда не создавалось» клиенту не раскрывается. |
Единые правила по истекшим согласиям. Возможность для клиента подтвердить факт существования согласия в прошлом (аудит, разбор инцидентов) до архивации. | GET /account-consents/{consentId} |
| Перечень событий, при которых ПУ рекомендуется перевести согласие в статус «Отозвано». | Согласие переводится в статус «Отозвано» внутренними средствами ПУ при наступлении одного из перечисленных событий. Дальнейшая выдача данных по этому согласию прекращается. | Предотвратить использование нелегитимных согласий и ограничить доступ к данным. | DELETE /account-consents/{consentId} и внутренние процессы ПУ, меняющие статус согласия |
GET /account-consents/{consentId} в зависимости от состояния согласияПри реализации конечной точки GET /account-consents/{consentId} у участников интеграций возник вопрос, какой ответ возвращать, когда срок действия согласия (expirationDateTime) истёк. Сейчас поведение расходится: часть участников возвращает 403, ссылаясь на недействительность согласия; часть — 200 и тело с истекшей датой. По итогам обсуждения большинством участников зафиксирована логика ниже.
Поведение определяется фактом нахождения согласия в оперативной базе ПУ (без привязки только к сроку действия).
expirationDateTime содержит прошедшую дату. Если согласие отозвано, но ещё не архивировано, возвращается объект со статусом «Отозвано» (Revoked). Это даёт клиенту возможность подтвердить факт существования согласия в прошлом — для аудита и выяснения обстоятельств.RU.CBR.Authenticate.InvalidConsent. Ресурс считается недоступным. Различие между «архивировано» и «никогда не создавалось» не раскрывается: клиенту возвращается одинаковый ответ (снижение риска перебора идентификаторов).Ключевое разделение: «истёкшее» ≠ «архивированное».
expirationDateTime, но запись хранится в оперативной базе. Оно остаётся читаемым через API (200 OK).Архивация — внутренний процесс ПУ. Стандарты Открытых API в настоящий момент не регламентируют процесс и сроки архивации согласий. Архивация остаётся внутренним механизмом оптимизации хранения данных в ПУ.
Конкретный срок архивации согласия предлагается определить совместным решением участников рабочей группы. До фиксации срока участникам рекомендуется:
expirationDateTime как основание для немедленного 403;Обработка и хранение данных после истечения или отзыва согласия — в соответствии с законодательством Российской Федерации и принципами {ОАПИ-П1}, {ОАПИ-ИБ2}. Настоящая рекомендация регулирует только код ответа метода чтения согласия, а не правомерность последующего информационного обмена по счетам.
Примеры сценариев
| Сценарий | HTTP-статус | Тело ответа / код ошибки |
|---|---|---|
| Согласие активно или истекло недавно, запись в оперативной базе | 200 OK | Полный объект согласия (expirationDateTime может быть в прошлом) |
| Согласие отозвано, но ещё не архивировано (запись в оперативной базе) | 200 OK | Объект согласия со статусом Revoked |
| Согласие истекло давно и архивировано | 403 Forbidden | RU.CBR.Authenticate.InvalidConsent |
consentId никогда не создавался |
403 Forbidden | RU.CBR.Authenticate.InvalidConsent |
Приведённые сценарии — случаи, при которых ПУ рекомендуется перевести ранее выданное согласие Пользователя в статус «Отозвано». Перечень не является исчерпывающим и может быть дополнен участниками рынка с учётом бизнес-процессов и требований законодательства.
После перевода согласия в статус «Отозвано» ПУ прекращает информационный обмен по этому согласию. Запись при этом может оставаться в оперативной базе и читаться по правилам п. 4.1.1 до архивации.
1. Отзыв согласия в ПУ по инициативе Пользователя
Пользователь прекращает действие ранее выданного согласия. Отзыв может быть инициирован любым способом, предусмотренным ПУ, например:
Основание — волеизъявление Пользователя. Рекомендуется согласовать это поведение с интерфейсом управления согласием на стороне ПУ ({ОАПИ-П2}: Пользователю доступен отзыв).
2. Установление Пользователем запрета на передачу данных третьим лицам
После выдачи согласия Пользователь устанавливает запрет на передачу своих данных третьим лицам либо иным способом запрещает обмен информацией о счёте. Дальнейшая передача данных в СПУ по ранее выданному согласию становится некорректной. ПУ рекомендуется перевести согласие в статус «Отозвано».
3. Ликвидация юридического лица, в отношении которого выдано согласие
Если организация, в отношении которой выдано согласие, прекращает существование в результате ликвидации, после завершения процедуры ликвидации использование согласия теряет практический смысл: субъект правоотношений прекращает существование. После получения ПУ информации о завершении ликвидации рекомендуется перевести согласие в статус «Отозвано».
Требуется дополнительная проработка общих правил для ИП и иных типов клиентов.
4. Банкротство организации (ЮЛ)
Если в отношении ЮЛ проводится процедура банкротства, возможность дальнейшего использования согласия зависит от стадии процедуры и правового статуса организации. Конкретные условия рекомендуется определить отдельными правилами с учётом законодательства и категорий клиентов. При невозможности дальнейшего правомерного использования согласия ПУ рекомендуется перевести его в статус «Отозвано». Необходима дальнейшая проработка.
5. Реорганизация юридического лица
Организация проходит реорганизацию (слияние, присоединение, разделение, выделение или преобразование). Могут измениться реквизиты, правопреемник или состав участников информационного обмена. Если после завершения реорганизации ПУ считает, что дальнейшее использование ранее выданного согласия невозможно либо не соответствует его первоначальным условиям, рекомендуется перевести согласие в статус «Отозвано».
Требуется определить единые правила для различных форм реорганизации (в том числе случаи, когда согласие может перейти к правопреемнику, а не отзываться автоматически).
Таблица 3 — Краткое описание кейсов отзыва согласия со стороны ПУ
| Кейс | Краткая суть | Рекомендуемые действия ПУ | Примечание |
|---|---|---|---|
| 1. Отзыв по инициативе Пользователя | Пользователь прекращает действие согласия любым предусмотренным ПУ способом. | Перевести согласие в статус «Отозвано» и прекратить его использование. | Основание — волеизъявление Пользователя. |
| 2. Запрет на передачу данных третьим лицам | После выдачи согласия Пользователь запрещает передачу данных третьим лицам или обмен информацией о счёте. | Перевести согласие в статус «Отозвано» и прекратить предоставление данных по нему. | Дальнейшая передача в СПУ противоречит требованию клиента. |
| 3. Ликвидация ЮЛ | Юридическое лицо прекращает существование в результате ликвидации. | После сведений о завершении ликвидации перевести согласие в статус «Отозвано». | Нужны общие правила для ИП и других типов клиентов. |
| 4. Банкротство ЮЛ | Процедура банкротства влияет на возможность использования согласия. | При невозможности правомерного использования перевести согласие в статус «Отозвано». | Условия — отдельно, с учётом стадии процедуры и категории клиента. |
| 5. Реорганизация ЮЛ | Слияние, присоединение, разделение, выделение или преобразование меняет субъекта или условия согласия. | Если использование невозможно или не соответствует первоначальным условиям — перевести в статус «Отозвано». | Нужны единые правила по формам реорганизации, включая правопреемство. |
Следующие пункты сознательно не зафиксированы как готовая практика и требуют решения участников до переноса в прикладной стандарт или спецификацию OpenAPI:
valueDateTime как допустимый суррогат.