Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Справочник API

Этот раздел — справочное руководство по кредитному API Waafir: HTTP-интерфейсу, через который финтех-компании передают данные портфеля в Waafir для мониторинга инвесторами. Здесь описаны все маршруты под /api/v1/monitoring/loan/, схемы запросов и ответов, все коды состояния, общий контракт для разработчиков и конверты ошибок, которые следует ожидать.

Справочник исчерпывающий, но не повествовательный. Если вы выполняете интеграцию впервые и вам нужен пошаговый сквозной рецепт — с параллельными примерами на cURL, TypeScript и Python, — читайте раздел «Сборник рецептов» вместе с этим справочником; они задуманы для совместного чтения.

Что охватывает API

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

  • CRUD для отдельных записей — один HTTP-вызов на строку. Используйте для операционных записей небольшого объёма: один новый кредит, один платёж, один переход статуса.
  • Пакетная загрузка NDJSON — до десяти тысяч строк в одном синхронном вызове. Используйте для пакетов на конец дня, которые умещаются в один HTTP-запрос.
  • Асинхронный импорт — прямая загрузка файла с последующей асинхронной обработкой. Используйте для исторических загрузок или любого пакета свыше десяти тысяч строк.
  • Сверка — обратное чтение отправленных строк по вашим собственным идентификаторам и подсчёт строк по сущностям. Используйте, чтобы убедиться, что вчерашняя отправка прошла чисто, прежде чем отправлять сегодняшнюю.

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

Шесть кредитных сущностей

Каждый маршрут работает с одной или несколькими из следующих сущностей. Их полные схемы описаны для каждого маршрута — этот список служит каталогом:

  • borrower — физическое или юридическое лицо, получающее кредит, с необязательными полями PII, которые маскируются при чтении.
  • loan — сам кредитный договор: основная сумма, валюта, APR, срок, периодичность погашения, статус.
  • scheduled_repayment — договорной график погашения, одна строка на каждую дату платежа.
  • actual_payment — фактически полученные платежи, включая списания и частичные платежи.
  • collateral — залог, предоставленный по кредиту.
  • collateral_valuation — оценки строки залога на определённый момент времени с поддержкой нескольких методов.

Каждая сущность принадлежит портфелю в вашей организации. Портфель указывается при каждой записи; организация определяется вашим персональным токеном доступа и никогда не указывается в теле запроса.

Аутентификация в одной строке

Каждый запрос содержит Authorization: Bearer <PAT>, где <PAT> — персональный токен доступа, выпущенный панелью управления Waafir. Токены ограничены организацией: токен, выпущенный организации A, не может читать или записывать данные организации B, а чтение данных другой организации возвращает 404 Not Found, а не 403 Forbidden, чтобы не раскрывать существование ресурсов другого клиента.

Полная модель аутентификации и авторизации описана в обзоре.

Как пользоваться этим справочником

Читайте страницы по порядку или переходите сразу к нужному интерфейсу:

  • Обзор — общий контракт, которому следует каждый кредитный маршрут: аутентификация, гарантии интеграции (идентификаторы, задаваемые вызывающей стороной, идемпотентность, пробные запуски), конверты ошибок, соглашения о денежных суммах и датах, семантика отмены и то, как фиксируется каждая отправка.
  • CRUD для отдельных записей — все маршруты POST, GET, PATCH и отмены для отдельных строк.
  • Пакетная загрузка NDJSON — синхронная пакетная загрузка с отчётом об ошибках по каждой строке.
  • Асинхронный импорт — двухфазная загрузка, опрос статуса и постраничный просмотр ошибок.
  • Сверка — обратное чтение по идентификатору вызывающей стороны и подсчёт строк по сущностям.
  • Ошибки и коды состояния — сводный каталог всех кодов состояния, конвертов ошибок и именованных кодов ошибок, которые возвращает кредитный API.

Руководства по задачам — сквозное подключение портфеля, ежедневная сверка, восстановление после частично неудачного импорта — см. в разделе «Сборник рецептов» (выпускается вместе с этим справочником). Этот раздел разбирает каждую задачу на трёх языках; этот справочник — первоисточник того, что каждый маршрут принимает и возвращает.

Чего нет в этом справочнике

  • Подключение и токены — как зарегистрировать организацию, создать портфель и выпустить персональный токен доступа. Эти процессы описаны в документации по администрированию платформы и в рецепте начала работы в разделе «Сборник рецептов».
  • Аналитика для инвесторов — наборы графиков, экспорт ленты и загрузка кредитной ленты. Они работают через отдельные маршруты и здесь не описаны.
  • Вебхуки и плановая доставка ленты — здесь не описаны.