Справочник 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.
Руководства по задачам — сквозное подключение портфеля, ежедневная сверка, восстановление после частично неудачного импорта — см. в разделе «Сборник рецептов» (выпускается вместе с этим справочником). Этот раздел разбирает каждую задачу на трёх языках; этот справочник — первоисточник того, что каждый маршрут принимает и возвращает.
Чего нет в этом справочнике
- Подключение и токены — как зарегистрировать организацию, создать портфель и выпустить персональный токен доступа. Эти процессы описаны в документации по администрированию платформы и в рецепте начала работы в разделе «Сборник рецептов».
- Аналитика для инвесторов — наборы графиков, экспорт ленты и загрузка кредитной ленты. Они работают через отдельные маршруты и здесь не описаны.
- Вебхуки и плановая доставка ленты — здесь не описаны.