Сборник рецептов
Этот сборник рецептов предназначен для инженеров финтех-компаний, которые подключают свой кредитный портфель к API мониторинга Waafir. Каждый рецепт проводит одну задачу от начала до конца со всеми тремя эталонными клиентами — cURL, TypeScript, Python, — чтобы читателю не приходилось мысленно переводить с одного языка на другой. Рецепты уделяют основное внимание сценариям сбоев и пограничных случаев, с которыми сталкивается реальная интеграция, а не только успешному сценарию.
Для кого это
Администратор вашей организации в Waafir выдал вам персональный токен доступа (PAT), и вы пишете код, который отправляет в Waafir ежедневные данные кредитной ленты — заёмщиков, кредиты, плановые погашения, фактические платежи, залоги и оценки залогов. Каждая отправка сначала записывается в том виде, в каком была отправлена, а затем сохраняется в виде строк; после этого она питает вкладку мониторинга для инвесторов в любой комнате данных, связанной с портфелем.
Как пользоваться рецептами
Все рецепты устроены одинаково: короткое вступление, три блока кода в фиксированном порядке и краткий абзац о проверке. Блоки кода:
- cURL — копируйте и вставляйте в свою оболочку. Наименее навязчивый вариант; удобен для разовых проверок и проверок в CI.
- TypeScript — на основе
fetchс использованием публичных JSON-контрактов. Установка SDK не требуется. - Python — на основе
requestsс использованием тех же JSON-контрактов. Достаточно стандартной библиотеки; специальный пакет Waafir не требуется.
Аутентификация
Все эндпоинты требуют PAT в заголовке Authorization:
Authorization: Bearer <YOUR_PAT>PAT привязан к одной организации Waafir и передаёт её идентичность в каждом запросе. Обращайтесь с ним как с секретом; при утечке замените его через панель управления. Базовый URL API во всех рецептах — https://app.waafir.io; замените его своим URL тестовой среды, если сначала интегрируетесь с тенантом-песочницей.
Соглашения, принятые в рецептах
- Все переменные оболочки в примерах cURL записаны как
${UPPER_CASE_NAME}, чтобы их можно было один раз задать черезexportи использовать во всех рецептах. - Примеры на TypeScript и Python предполагают, что
BASE_URLиPATсчитываются из окружения. Адаптируйте под свой загрузчик конфигурации. - Заголовок
Idempotency-Key— общее для платформы соглашение о безопасных повторах; точную семантику см. в рецепте о повторах. - Все эндпоинты записи принимают ваши собственные значения
external_id— идентификаторы, переданные вызывающей стороной, остаются каноническим дескриптором на протяжении загрузки, сверки и скачивания ленты. Вам никогда не нужно знать внутренние UUID Waafir.
Чего нет в сборнике рецептов
Сборник рецептов ориентирован на задачи. Исчерпывающие определения эндпоинтов, схемы запросов и ответов и справочник кодов ошибок см. в разделе справки по API, когда он появится вместе со сборником рецептов. О концепциях продукта, например о том, что такое портфель и как он связан с комнатой данных, см. Комнаты данных и раздел базовых концепций.
Рецепты
- Массовый импорт кредитной ленты через асинхронный NDJSON — базовый процесс загрузки: прямая выгрузка файла, фиксация, опрос до завершения.
- Проверка загрузки в режиме dry-run перед фиксацией данных — тот же процесс с
?dryRun=true; узнайте, что содержит ваш файл, до записи каких-либо строк. - Безопасный повтор с ключом идемпотентности — переживите кратковременные сетевые сбои, не создавая дублирующих импортов.
- Разбор ошибок частичного сбоя после импорта — постраничный просмотр ошибок по строкам, когда импорт завершается со статусом
partial. - Отмена выполняющегося импорта — остановите длительный импорт на границе следующего пакета без частично записанных строк.
- Сверка данных по внешнему ID — убедитесь по собственному идентификатору, что строка записана, и проверьте ежедневные количества.