Сверка
Интерфейс сверки позволяет проверить, что попало в Waafir, используя ваши собственные идентификаторы, а не UUID, присвоенные платформой. Он намеренно минимален — два маршрута, — но служит операционной основой надёжной интеграции: каждая исправная ежедневная загрузка завершается вызовом сверки.
Зачем сверять по идентификатору вызывающей стороны
Когда вы отправляете кредит с externalId: "L-001", ваша система уже знает строку под этим именем. Спросить платформу «есть ли у вас L-001?» — естественный следующий шаг, а отсутствие необходимости сначала переводить его в UUID платформы означает, что ваша логика сверки может работать с теми же идентификаторами, что и ваш учёт.
Платформа гарантирует, что externalId уникален в пределах портфеля среди действующих строк, и именно поэтому поиск по externalId — это чтение одной строки.
Маршруты
| Метод | Путь | Назначение |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | Прочитать один кредит по идентификатору вызывающей стороны. |
GET | /api/v1/monitoring/loan/counts | Прочитать итоговое число строк по сущностям, при необходимости с фильтром по портфелю, дате или сущности. |
GET /api/v1/monitoring/loan/loans/{externalId}
Читает один кредит по переданному вами externalId. Отменённые (мягко удалённые) строки исключаются.
Запрос
| Параметр | Расположение | Обязательный | Ограничение |
|---|---|---|---|
externalId | path | да | 1-255 символов; символы, небезопасные для URL, кодируйте процентным кодированием. |
portfolioId | query | да | UUID портфеля, которому принадлежит кредит. |
portfolioId обязателен, потому что externalId не уникален между портфелями — он уникален только в пределах портфеля.
Ответ — 200 OK
{
"loan": {
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "L-001",
"predecessorLoanId": null,
"principalAmount": "10000.0000",
"currencyCode": "USD",
"interestRateApr": "0.180000",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"productType": "Term loan",
"status": "active",
"metadata": {},
"createdAt": "2026-01-15T08:00:00Z",
"updatedAt": "2026-01-15T08:00:00Z"
},
"borrower": {
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "B-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null
}
}Ответ включает заёмщика по кредиту с маскированными PII. Это представление для инвесторов — то же маскирование, что и у эндпоинта GET заёмщика. Маскирование позволяет подтвердить, что «этот кредит привязан к нужному заёмщику», не раскрывая PII вызывающей системе. Администраторы, которым нужны исходные PII, используют интерфейс чтения заёмщика по UUID с ?unmask=true и записью в журнал аудита.
Денежные поля возвращаются с полной сохранённой точностью (четыре знака после запятой для денежных сумм; шесть для interestRateApr); ваш клиент должен обрабатывать их как непрозрачные десятичные строки, а не преобразовывать в числа с плавающей точкой.
Коды состояния
| Статус | Условие |
|---|---|
200 OK | Кредит найден в вашей организации. |
400 Bad Request | portfolioId отсутствует или некорректен, либо externalId содержит некорректное процентное кодирование. |
404 Not Found | Кредит не существует как действующий в указанном портфеле, или портфель принадлежит другой организации. |
cURL
curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
-H "Authorization: Bearer $WAAFIR_PAT"GET /api/v1/monitoring/loan/counts
Читает количество строк по сущностям, при необходимости с фильтром по портфелю, по дате или по одной сущности. Мягко удалённые строки исключаются.
Запрос
| Параметр | Расположение | Обязательный | Ограничение |
|---|---|---|---|
portfolioId | query | нет | UUID; ограничивает выборку одним портфелем. Не указывайте для сводки по всей организации. |
date | query | нет | YYYY-MM-DD; если указан, ответ содержит счётчик onDate для каждой сущности. |
entity | query | нет | Одно из borrowers, loans, scheduled_repayments, actual_payments, collateral, collateral_valuations (без учёта регистра). Если указан, возвращается только эта сущность. |
Ответ — 200 OK
Сводка по умолчанию, все шесть сущностей:
{
"counts": {
"borrowers": { "total": 1200 },
"loans": { "total": 3450 },
"scheduled_repayments": { "total": 41400 },
"actual_payments": { "total": 32118 },
"collateral": { "total": 600 },
"collateral_valuations": { "total": 1840 }
},
"date": null,
"portfolioId": null
}С ?date=2026-05-22 каждая сущность получает счётчик onDate — число строк, созданных в указанную дату:
{
"counts": {
"borrowers": { "total": 1200, "onDate": 0 },
"loans": { "total": 3450, "onDate": 12 },
"scheduled_repayments": { "total": 41400, "onDate": 144 },
"actual_payments": { "total": 32118, "onDate": 1207 },
"collateral": { "total": 600, "onDate": 0 },
"collateral_valuations": { "total": 1840, "onDate": 0 }
},
"date": "2026-05-22",
"portfolioId": null
}С ?entity=loans в ответе присутствует только запись loans.
Коды состояния
| Статус | Условие |
|---|---|
200 OK | Запрос разобран; счётчики возвращены. |
400 Bad Request | Некорректный portfolioId, date или entity. |
portfolioId, который не существует или принадлежит другой организации, не возвращает 404; он возвращает 200 с нулями по всем позициям. Так задумано: интерфейс счётчиков читает ваши собственные данные, а неизвестный портфель функционально неотличим от портфеля без строк.
cURL
# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
-H "Authorization: Bearer $WAAFIR_PAT"Типичная ежедневная сверка
После завершения сегодняшних отправок канонический порядок сверки таков:
- Вызовите
GET /counts?date=<today>для своего портфеля. Сравните счётчикonDateдля каждой сущности с тем, что вы отправили сегодня. Если счётчики совпадают с отправленным, ваш пакет загружен чисто. - При любом расхождении найдите конкретные строки с помощью
GET /loans/{externalId}. Такие запросы дёшевы — по одному сканированию индекса на каждый — и возвращают каноническое состояние строки, включая UUID, присвоенный платформой, который затем можно использовать для дальнейшего расследования. - Для расследования на уровне строк подробности о сбоях по строкам предоставляют эндпоинты GET для отдельных записей и эндпоинт постраничного вывода ошибок асинхронного импорта.
Интерфейс сверки намеренно только для чтения и недорог — это пульс интеграции, а не интерфейс для нагрузки. Вызывайте его один-два раза в день для каждого портфеля; специального ограничения частоты для него нет, но, пожалуйста, не опрашивайте его в плотном цикле.