Регламент информационного взаимодействия по API

1. Общие положения

1.1. Настоящий Регламент информационного взаимодействия по API (далее — Регламент) является неотъемлемой частью Общих условий подключения кредиторов к платформе «Финарена» (далее — Общие условия) и устанавливает технические правила обмена сообщениями между Платформой, оператором которой является Общество с ограниченной ответственностью «Тензор» (далее — Оператор), и Кредитором. Термины используются в значении Общих условий.

1.2. Описание методов (эндпоинтов), структур сообщений, кодов ошибок и примеры приводятся в документации API, размещённой в Личном кабинете Кредитора (далее — документация API). Документация API детализирует Регламент и не может ему противоречить.

1.3. Требования Регламента обязательны для обеих Сторон. Каждая Сторона назначает ответственного за интеграцию и технического специалиста для связи по инцидентам.

2. Архитектура обмена

2.1. Обмен осуществляется в двух направлениях:

Платформа → Кредитор: запросы к API Кредитора (Бронь, Пакет, выбор Клиента, проверка доступности) и уведомления Платформы;
Кредитор → Платформа: вызовы API Платформы и вебхуки Кредитора (Решения, статусы, сведения о выдаче займов, отказы по программе «Отказной трафик», справочник продуктов).

2.2. Бронь выполняется синхронно: ответ возвращается в том же HTTP-соединении. Пакет и выбор Клиента передаются асинхронно: Кредитор подтверждает приём сообщения HTTP-ответом с кодом 2xx, а Решение и статусы направляет отдельными запросами (вебхуками) к API Платформы. Синхронный возврат Решения допускается, если это предусмотрено документацией API.

2.3. Каждая Сторона поддерживает тестовый и промышленный контуры с раздельными адресами, ключами и секретами. Передача реальных персональных данных в тестовый контур запрещена.

2.4. Если Кредитор не поддерживает стандартный протокол Платформы, Оператор подключает его через адаптер к существующему API Кредитора (пункт 3.6 Общих условий). Требования Регламента к срокам, безопасности и журналированию применяются и в этом случае.

3. Типы сообщений

3.1. Бронь (Платформа → Кредитор): номер телефона Клиента и идентификатор запроса. Ответ — статус reserved («закреплён за Платформой») или in_work («уже в работе»).

3.2. Пакет (Платформа → Кредитор) содержит:

идентификатор передачи и параметры Заявки: категорию продукта, запрашиваемые сумму и срок;
данные Клиента: фамилию, имя, отчество, дату и место рождения, паспортные данные и изображения паспорта, адреса регистрации и проживания, ИНН, СНИЛС, статус индивидуального предпринимателя или плательщика налога на профессиональный доход, телефон и адрес электронной почты;
данные предмета залога (при наличии): VIN, марку, модель, год выпуска, объём и мощность двигателя, вид топлива, цвет, пробег, даты смены собственника;
результаты проверок без указания источников: действительность паспорта, розыск лица и транспортного средства, аресты и ограничения регистрационных действий, нахождение в реестре залогов, признаки банкротства, наличие самозапрета; значения результата — clear (не выявлено), found (выявлено), not_checked (не проверялось), error (ошибка проверки);
подписанные документы в формате PDF и данные подписи: дату и время, номер телефона, IP-адрес, user-agent, хеш-суммы SHA-256 каждого документа и пакета в целом.

3.3. Решение (Кредитор → Платформа):

approved — код и наименование продукта, лимит (и минимальная сумма, если применимо), процентная ставка или диапазон ставок с единицей измерения (в день или годовых), срок или диапазон сроков, срок действия Предодобрения, а при наличии — полная стоимость займа, ежемесячный платёж, особые условия и ссылка на личный кабинет Кредитора;
declined — обобщённый код причины отказа.

Решение approved без процентной ставки или диапазона ставок не принимается.

3.4. Выбор Клиента (Платформа → Кредитор): выбранный продукт, сумма и срок. Кредитор в ответе передаёт свой идентификатор заявки, если он не был передан в Решении, и, при наличии, ссылку для перехода Клиента в личный кабинет Кредитора. Кредиторам, предложения которых не выбраны, направляется уведомление not_chosen; их Бронь сохраняется.

3.5. Статусы (Кредитор → Платформа):

identification — идентификация Клиента;
inspection — осмотр предмета залога;
signing — подписание договора;
issued — заём выдан (сумма, дата выдачи, номер договора или внутренний идентификатор);
lender_rejected — отказ после пересмотра с кодом основания: unreliable_data (недостоверные данные Клиента), illegal_actions (признаки противоправных действий), collateral_condition (состояние залога хуже нормального износа более чем на 10 % оценки);
client_refused — отказ Клиента.

Статусы issued, lender_rejected и client_refused являются финальными; последующие статусы по той же передаче не принимаются. При отказе, обязательном в силу закона (пункт 6.6 Общих условий), код основания не указывается.

3.6. Сведения о выдаче по Брони (Кредитор → Платформа): сообщение о займе, выданном в Срок Брони Клиенту, обратившемуся к Кредитору напрямую или через иные каналы, — идентификатор Брони или номер телефона, сумма и дата выдачи.

3.7. Отказы (Кредитор → Платформа): для участников программы «Отказной трафик» — данные заявителя, которому Кредитор отказал, с доказательствами согласия на передачу данных Оператору (версия и хеш формы, дата и время, способ получения).

3.8. Справочник продуктов (Кредитор → Платформа): коды, наименования и категории продуктов, диапазоны сумм, сроков, процентных ставок и полной стоимости займа, требования к заёмщику и предмету залога. Справочник носит информационный характер.

3.9. Уведомления Платформы (Платформа → Кредитор): окончание или досрочное прекращение Брони, отмена Заявки Клиентом, отзыв Клиентом согласия, поданный через Платформу, изменение параметров интеграции. Платформа периодически проверяет доступность API Кредитора (health-check).

4. Форматы

4.1. Транспорт — HTTPS. Формат — JSON в кодировке UTF-8 (Content-Type: application/json; charset=utf-8).

4.2. Дата и время передаются в формате ISO 8601 с указанием часового пояса (рекомендуется UTC), даты без времени — в формате ГГГГ-ММ-ДД. Денежные суммы — числом в рублях с точностью до копеек; проценты — числом (7 означает 7 %); номер телефона — 11 цифр, начиная с 7 (например, 79991234567).

4.3. Идентификаторы Платформы — UUID; идентификаторы Кредитора — строки длиной до 64 символов. Кредитор использует свой идентификатор заявки во всех последующих статусах.

4.4. Файлы (PDF, изображения) передаются по ссылкам с ограниченным сроком действия (не менее 24 часов), доступ к которым требует аутентификации, либо в теле сообщения в кодировке Base64 — в соответствии с документацией API. Максимальный размер сообщения — 20 МБ, если документация API не устанавливает иное.

4.5. Ошибки возвращаются с HTTP-кодом 4xx или 5xx и телом, содержащим объект error с полями code (код ошибки), message (описание) и details (подробности). Получатель игнорирует неизвестные ему поля сообщения.

5. Аутентификация и белые списки

5.1. Запросы к API Платформы аутентифицируются API-ключом, который передаётся в заголовке, указанном в документации API. Ключ выпускается в Личном кабинете, отображается один раз и хранится Платформой только в виде хеша. Для тестового и промышленного контуров выпускаются разные ключи; на время ротации допускается одновременное действие двух ключей.

5.2. Запросы принимаются только с IP-адресов из белого списка, заданного Кредитором в Личном кабинете, — до 30 адресов или подсетей на ключ. Запросы с иных адресов отклоняются с кодом 403.

5.3. Запросы Платформы к API Кредитора аутентифицируются способом, поддерживаемым API Кредитора (API-ключ, Basic- или Bearer-аутентификация), и направляются с IP-адресов Платформы, опубликованных в Личном кабинете. Об изменении этих адресов Оператор уведомляет не менее чем за 5 рабочих дней.

6. Подпись сообщений

6.1. Запросы и вебхуки в обоих направлениях, включая запрос Брони, подписываются кодом аутентификации HMAC-SHA256 с секретом, выпущенным в Личном кабинете для соответствующего контура.

6.2. Подписывается строка, состоящая из метки времени отправки (Unix-время в секундах), символа точки и неизменённого тела запроса. Метка времени и подпись в шестнадцатеричном виде передаются в заголовках, указанных в документации API.

6.3. Получатель вычисляет подпись, сравнивает её с полученной способом, исключающим атаки по времени, и отклоняет сообщение с кодом 401, если подпись неверна или метка времени отличается от текущего времени более чем на 5 минут. Стороны синхронизируют системное время по протоколу NTP.

7. Идемпотентность и повторы

7.1. Каждый запрос, изменяющий состояние, содержит заголовок Idempotency-Key с уникальным значением (рекомендуется UUID). Получатель хранит ключ и результат обработки не менее 24 часов и при повторном запросе с тем же ключом возвращает прежний результат без повторной обработки. Запрос с тем же ключом, но иным телом отклоняется с кодом 409.

7.2. Повторная доставка не должна создавать дублей: одной передаче соответствует одно Решение, финальный статус не изменяется, сведения о выдаче учитываются однократно.

7.3. При сетевой ошибке, таймауте или ответе с кодом 408, 425, 429 или 5xx отправитель повторяет доставку асинхронного сообщения с экспоненциально возрастающим интервалом (1, 2, 4, 8, 16, 32 минуты, далее — ежечасно) в течение 24 часов с момента первой попытки. При ответе 429 соблюдается интервал из заголовка Retry-After. Иные ошибки 4xx не повторяются и требуют исправления запроса. Недоставленные сообщения отражаются в журнале обмена в Личном кабинете.

7.4. Запрос Брони за пределами отведённой минуты не повторяется: при отсутствии ответа Бронь считается неполученной.

8. Сроки (SLA)

8.1. Стороны соблюдают следующие сроки:

Сообщение	Направление	Срок
Ответ на запрос Брони	Кредитор → Платформа, синхронно	не более 1 минуты (рекомендуется до 5 секунд)
Подтверждение приёма асинхронного сообщения	получатель → отправитель	не более 10 секунд
Решение по Пакету	Кредитор → Платформа	не более 15 минут с момента доставки Пакета, если иной срок не указан в карточке интеграции (пункт 8.2)
Статусы оформления	Кредитор → Платформа	не позднее 1 рабочего дня с даты события
Сведения о выдаче по Брони	Кредитор → Платформа	не позднее 1 рабочего дня с даты выдачи
Изменение справочника продуктов	Кредитор → Платформа	не позднее дня изменения условий
Уведомление об отзыве согласия	Платформа → Кредитор	не позднее 1 рабочего дня с даты поступления

8.2. Решения принимаются автоматически и круглосуточно. Если автоматическое принятие Решений у Кредитора работает не круглосуточно, часы его работы и срок Решения согласовываются с Оператором и фиксируются специалистом Оператора в карточке интеграции Кредитора в CRM Платформы. Срок Решения, указанный в карточке интеграции, применяется вместо срока, указанного в таблице пункта 8.1, в том числе при расчёте крайнего срока Решения, передаваемого в Пакете. Пакеты направляются по мере поступления Заявок, в том числе вне согласованных часов работы.

8.3. Решение, полученное после истечения срока, Платформа вправе не учитывать. Если в течение календарного месяца нарушен срок по более чем 5 % Пакетов, Оператор вправе снизить приоритет Кредитора при распределении Заявок или временно исключить его из распределения.

9. Тестовый контур и приёмочные испытания

9.1. После регистрации Кредитор выпускает в Личном кабинете тестовые ключи (с префиксом fa_test_), указывает в настройках интеграции адрес своего тестового контура и включает тестовый режим. Тестовые ключи работают только с Заявками тестового контура, данные которых помечены признаком тестового контура (test). Для проверки своей реализации Кредитор может использовать песочницу Платформы — эталонную реализацию стороны Кредитора (/api/sandbox/lender: бронь, приём Пакета с синхронным Решением, выбор Клиента, эхо-запрос для проверки подписи и формата), если она включена Оператором; описание — в документации API.

9.2. Приёмочные испытания включают как минимум сценарии: Бронь с ответами reserved и in_work; отсутствие ответа на Бронь; Пакет с Решениями approved и declined; нарушение срока Решения; выбор Клиента и последовательность статусов до issued; отказ после пересмотра по каждому основанию; отказ Клиента; повторная доставка с тем же Idempotency-Key; отклонение сообщения с неверной подписью или устаревшей меткой времени; сведения о выдаче по Брони.

9.3. Испытания проводятся на тестовом контуре: Оператор направляет тестовые Заявки в тестовую интеграцию Кредитора, Кредитор отвечает с использованием тестового ключа. Успешное прохождение испытаний Стороны подтверждают обменом сообщениями по электронной почте между ответственными за интеграцию (со стороны Оператора — support@finarena.ru). После этого специалист Оператора переключает интеграцию Кредитора на промышленный контур, и Кредитор использует промышленные ключи (с префиксом fa_live_), выпущенные в Личном кабинете.

9.4. О существенных изменениях своих API Кредитор уведомляет Оператора не менее чем за 10 рабочих дней и проводит повторные испытания затронутых сценариев.

10. Доступность и плановые работы

10.1. Целевой показатель доступности промышленного API каждой Стороны — 99,5 % времени в календарном месяце без учёта плановых работ, о которых уведомлено в установленном порядке. Доступность измеряется по данным мониторинга Платформы.

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

10.3. О плановых работах, влекущих недоступность API, Сторона уведомляет другую Сторону через Личный кабинет или по электронной почте не менее чем за 3 рабочих дня. Плановые работы рекомендуется проводить с 00:00 до 06:00 по московскому времени; их суммарная продолжительность — не более 8 часов в месяц. О внеплановых работах уведомление направляется незамедлительно.

11. Инциденты

11.1. Контакты для инцидентов: со стороны Кредитора — технический специалист, указанный в Заявлении о присоединении; со стороны Оператора — служба поддержки support@finarena.ru и контакты, опубликованные в Личном кабинете.

11.2. Инциденты классифицируются как критические (недоступность API, массовые ошибки обработки, компрометация ключей, утечка персональных данных или неправомерный доступ к ним), высокие (нарушение сроков, ошибки обработки части сообщений) и обычные.

11.3. Время реакции — подтверждение принятия инцидента в работу и назначение ответственного — не более 4 часов с момента уведомления; по критическим инцидентам — круглосуточно. Стороны принимают меры к восстановлению в кратчайший срок и информируют друг друга о ходе работ.

11.4. По критическому инциденту Сторона, на стороне которой он возник, в течение 5 рабочих дней направляет отчёт о причинах и принятых мерах. Об инцидентах с персональными данными Стороны уведомляют друг друга не позднее 24 часов с момента выявления.

12. Журналирование и хранение

12.1. Платформа журналирует все входящие и исходящие сообщения: дату и время, направление, метод, адрес, HTTP-код, длительность, Idempotency-Key, хеш тела сообщения и результат обработки. Персональные данные в журналах маскируются или хранятся в зашифрованном виде.

12.2. Сроки хранения:

журнал обмена (метаданные и хеши сообщений) — не менее 5 лет;
подписанные документы и данные подписи — не менее 5 лет с даты подписания;
содержимое сообщений с персональными данными — не менее 1 года, но не дольше срока, допускаемого согласиями Клиента и законодательством;
журнал действий пользователей Личного кабинета — не менее 3 лет.

12.3. Кредитор ведёт журнал входящих и исходящих сообщений и хранит его не менее 3 лет.

12.4. Данные журналов используются для расчётов, разрешения споров и расследования инцидентов. Выписки из журнала обмена доступны Кредитору в Личном кабинете.

13. Запросы доказательств

13.1. Кредитор вправе запросить через Личный кабинет или ЭДО доказательства по Заявке, указав номер Заявки, идентификатор передачи или Брони либо номер телефона: PDF подписанного пакета документов, данные подписи, тексты и версии подписанных документов, выписку из журнала обмена.

13.2. Оператор предоставляет доказательства в течение 2 рабочих дней с даты запроса, при необходимости — в форме электронного документа, подписанного КЭП Оператора.

13.3. Оператор вправе запросить у Кредитора выписки из его журнала обмена и иные сведения, необходимые для разрешения спора или расследования инцидента; Кредитор предоставляет их в течение 5 рабочих дней.

14. Версионирование

14.1. Версия API указывается в адресе метода. Обратно совместимые изменения (новые методы, новые необязательные поля и параметры) вносятся с уведомлением через журнал изменений в Личном кабинете.

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

14.3. Изменения, необходимые для устранения угроз безопасности или исполнения требований законодательства, могут вводиться в более короткий срок с незамедлительным уведомлением.

15. Требования безопасности

15.1. Используется протокол TLS версии не ниже 1.2 (рекомендуется 1.3) с сертификатами доверенных удостоверяющих центров; протоколы SSL, TLS 1.0 и 1.1 и нестойкие наборы шифров не допускаются.

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

15.3. Доступ к Личному кабинету и API предоставляется по принципу минимально необходимых прав и только по персональным учётным записям; рекомендуется двухфакторная аутентификация. Доступ уволенных работников прекращается не позднее рабочего дня, следующего за днём увольнения.

15.4. Стороны обеспечивают защиту персональных данных в соответствии с Федеральным законом от 27.07.2006 № 152-ФЗ «О персональных данных», постановлением Правительства Российской Федерации от 01.11.2012 № 1119 и приказом ФСТЭК России от 18.02.2013 № 21, а Кредитор — также в соответствии с применимыми к нему требованиями Банка России, в том числе ГОСТ Р 57580.1-2017. Персональные данные обрабатываются в базах данных, находящихся на территории Российской Федерации.

15.5. Платформа хранит персональные данные Клиентов в зашифрованном виде. Кредитор обеспечивает сопоставимый уровень защиты данных, полученных по API.

16. Последствия нарушений

16.1. Нарушение Регламента является нарушением Договора. При угрозе безопасности информации Оператор вправе незамедлительно отозвать ключи и приостановить обмен с последующим уведомлением Кредитора.

16.2. Ответственность Сторон определяется Общими условиями.