Обзор
Все кредитные эндпоинты подчиняются контракту, описанному на этой странице. Прочитайте её первой: страницы отдельных интерфейсов ссылаются на неё, а не повторяют её содержание.
Базовый URL и версионирование
Все кредитные маршруты размещены под /api/v1/monitoring/loan/. Целое число после v — это мажорная версия: повышение мажорной версии означает несовместимое изменение и происходит только после явного уведомления об устаревании. Развитие в пределах мажорной версии — только аддитивное: новые необязательные поля, новые эндпоинты, новые значения перечислений — и никогда не ломает интеграцию, которая игнорирует непонятные ей поля.
Рабочий хост — https://app.waafir.io. Чтобы получить полный URL, добавьте хост перед любым путём из этого справочника, например https://app.waafir.io/api/v1/monitoring/loan/borrowers.
Аутентификация
Каждый запрос содержит заголовок Authorization с Bearer-токеном:
Authorization: Bearer <PAT><PAT> — персональный токен доступа, выпущенный в панели управления Waafir для одной организации. Организация токена определяет границы арендатора для каждого чтения и каждой записи — ни в одном URL или теле запроса нет параметра организации, потому что токен уже её фиксирует.
Запросы к данным другой организации возвращают 404 Not Found, а не 403 Forbidden. Ответ 403 раскрыл бы существование ресурса другого клиента по его id; при подходе с 404 неизвестные id и id другого клиента обрабатываются одинаково.
Запрос без заголовка Authorization, с неизвестным или с отозванным токеном возвращает 401 Unauthorized.
Гарантии интеграции
Каждый изменяющий маршрут соблюдает перечисленные ниже гарантии. На каждую из них может опираться ваш клиентский код; прочитав их здесь один раз, вы сможете реализовать надёжную интеграцию за один проход.
Идентификаторы, задаваемые вызывающей стороной
У каждой сущности в теле запроса есть поле id, которое вы передаёте в виде UUID. Платформа никогда не придумывает идентификаторы за вас. На этом основаны все остальные гарантии из списка: идемпотентность, сверка и повторное воспроизведение зависят от того, что вы можете обратиться к строке по выбранному вами идентификатору.
Если вы повторно отправите POST со строкой с тем же id, вы получите 409 ID_CONFLICT и запись fieldErrors, указывающую на id. Выбирайте идентификаторы тщательно — рекомендуются сгенерированные UUIDv4, но подойдёт любой корректный UUID.
Помимо id, каждая сущность также содержит externalId — произвольную строку длиной до 255 символов, по которой вы обращаетесь к строке из своей системы. externalId уникален в пределах портфеля среди действующих строк, и именно это делает возможной сверку по идентификатору вызывающей стороны.
Заголовок Idempotency-Key
Каждый изменяющий маршрут читает необязательный HTTP-заголовок Idempotency-Key. Если он передан, платформа выполняет дедупликацию по внутреннему архиву: второй запрос с тем же ключом возвращает тот же ответ, что и первый, даже если тело немного отличается. Так клиенты переживают сетевые сбои, после которых непонятно, дошёл ли запрос.
Заголовок не чувствителен к регистру при передаче (Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY — все варианты работают). Значение считается непрозрачным — выберите что-то стабильное для каждой логической операции, обычно UUIDv4 плюс признак маршрута.
?dryRun=true
Каждый изменяющий маршрут принимает параметр запроса ?dryRun=true. Пробный запрос выполняет проверку данных и проверку принадлежности арендатору и возвращает проверенные входные данные, но ничего не фиксирует и не сохраняет строку. Используйте его, чтобы убедиться, что тело разбирается корректно, прежде чем выполнять реальную запись.
Успешный пробный запуск возвращает 200 OK с ответом вида { "dryRun": true, "validatedInput": <body> }. Ошибки проверки при пробном запуске возвращают тот же ответ 400, что и реальная запись; различаются только побочные эффекты.
Конверт проверки fieldErrors
Ошибки проверки возвращают 400 Bad Request со структурированным конвертом:
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}path — путь к проблемному полю через точку; message — понятное человеку объяснение. Конверт одинаков для всех маршрутов, поэтому один клиентский обработчик может единообразно отображать любую ошибку проверки.
Перечисления без учёта регистра с подсказками «возможно, вы имели в виду»
Доменные перечисления (статус кредита, способ платежа, периодичность погашения, код валюты и т. д.) принимаются в любом регистре. Перед сохранением платформа приводит значение к канонической форме в нижнем регистре.
При несовпадении возвращается 400 с записью fieldErrors, которая называет проблемное значение и предлагает ближайшее допустимое:
{
"error": "Validation failed",
"fieldErrors": [
{
"path": "status",
"message": "got 'restruktured', did you mean 'restructured'?"
}
]
}Подсказка вычисляется по простой метрике редакционного расстояния, поэтому перестановки букв и одиночные опечатки надёжно распознаются.
Сквозная передача metadata JSONB
Каждая сущность принимает необязательное поле metadata типа object. Платформа сохраняет объект дословно — никакие ключи не удаляются, никакие значения не преобразуются. Используйте его, чтобы прикрепить клиентский контекст, который самой платформе понимать не нужно: ваш внутренний ID, исходную систему, отметку времени выгрузки, код кампании.
Два интерфейса не принимают metadata: переход статуса кредита и маршруты отмены платежа. Причины описаны непосредственно у этих маршрутов.
Сверка по идентификатору вызывающей стороны
К каждой сущности можно обратиться по переданному вами externalId в пределах портфеля. Интерфейс сверки — GET /loans/{externalId} и GET /counts — использует это, чтобы вы могли проверять записи, не зная UUID, присвоенного платформой. Точные форматы см. на странице сверки.
Представление денежных сумм
Денежные значения передаются как строки из десятичных цифр с не более чем четырьмя знаками после запятой. JavaScript number отклоняется, потому что двоичные числа с плавающей точкой IEEE-754 не могут точно представлять десятичные центы:
{ "amount": "100.50", "currencyCode": "USD" }Десятичное число с более чем четырьмя знаками после запятой или значение, содержащее символы, кроме цифр, ведущего минуса и одной точки, возвращает 400 с записью fieldErrors. Пустые строки отклоняются.
Коды валют — трёхбуквенные коды ISO-4217. Платформа явно распознаёт распространённый набор; неизвестные коды, соответствующие формату из трёх заглавных букв, принимаются и сохраняются дословно, чтобы не блокировать коды экзотических рынков.
Формат дат
Даты передаются как календарные строки ISO-8601 в формате YYYY-MM-DD:
{ "disbursementDate": "2026-01-15" }Часового пояса нет. Даты — это календарные даты в интерпретации портфеля; платформа их не преобразует.
Семантика отмены
Вызовы API никогда не стирают строку. Отмена или иное сторнирование вместо этого помечает строку как отменённую. Последствия:
- Отмена не освобождает
externalId.externalIdуникален в пределах портфеля только среди действующих строк. Отменённая строка больше не является действующей, поэтому еёexternalIdможно повторно использовать для исправленной отправки. - Чтения для сверки по умолчанию не возвращают отменённые строки. Интерфейсы
GET /loans/{externalId}иGET /countsисключают мягко удалённые строки из ответа по умолчанию. - Записи об отправке сохраняются в любом случае. Даже если строка отменена, запись об отправке, которая её создала, остаётся нетронутой для аудита.
Каждая отправка фиксируется
Каждое успешное изменение записывает исходное тело запроса до того, как будет записана строка. Последствия для вашей интеграции:
200/201означает, что ваша отправка надёжно зафиксирована, даже если последующая обработка позже пометит её. Ваш аудиторский след начинается в момент, когда платформа подтверждает запрос.409 ID_CONFLICTтоже архивируется. Запись об отправке содержит и конфликт, и попытку отправки, поэтому позже вы сможете разобраться без неясности в том, что было отправлено.- Асинхронный импорт фиксируется в момент подтверждения (commit). Записью служат загруженный файл NDJSON и сам импорт; отдельной записи по каждой строке для асинхронного импорта нет.
Запись об отправке изменить нельзя. Вы никогда не читаете её напрямую через публичный API, но именно поэтому интерфейс сверки авторитетен — за каждой видимой в нём строкой стоит соответствующая запись в архиве.
Как устроена остальная часть справочника
Каждая следующая страница этого справочника описывает один способ загрузки или интерфейс сверки. Страница каждого маршрута построена одинаково: назначение в одном предложении, формат запроса (заголовки, параметры запроса, тело), формат ответа для каждого кода состояния и минимальный вызов cURL. Ограничения по каждому полю собраны в таблицах, которые удобно просматривать; подробные примеры и образцы кода на трёх языках — в разделе «Сборник рецептов».
Страница ошибок и кодов состояния — сводный справочник по конвертам ответов, которые используют все маршруты этого сайта. Прочитайте её один раз перед интеграцией и возвращайтесь к ней всякий раз, когда статус, отличный от 200, окажется неожиданным.