CRUD для отдельных записей
Интерфейс CRUD для отдельных записей — путь для небольших объёмов: один HTTP-вызов на строку. Используйте его для операционных записей — одного нового кредита, одного платежа, который не попал в ежедневный пакет, перехода статуса — и для обратного чтения по UUID платформы. Для пакетов на конец дня используйте пакетную загрузку NDJSON; для исторических загрузок — асинхронный импорт.
Каждый маршрут на этой странице соблюдает контракт, описанный в обзоре: аутентификацию по bearer-токену, гарантии интеграции, конверт fieldErrors, семантику отмены и фиксацию каждой отправки. В описании маршрутов ниже названы только форматы, специфичные для маршрута; за сквозным поведением обращайтесь к обзору.
Маршруты кратко
| Метод | Путь | Назначение |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | Создать заёмщика |
GET | /api/v1/monitoring/loan/borrowers/{id} | Прочитать заёмщика по UUID с маскированием PII |
POST | /api/v1/monitoring/loan/loans | Создать кредит |
POST | /api/v1/monitoring/loan/payments | Создать фактический платёж |
GET | /api/v1/monitoring/loan/payments/{id} | Прочитать фактический платёж по UUID |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | Перевести кредит в новый статус |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | Мягко удалить платёж |
Все изменяющие маршруты принимают заголовок Idempotency-Key и параметр запроса ?dryRun=true, а при ошибке проверки возвращают структурированный конверт fieldErrors.
POST /api/v1/monitoring/loan/borrowers
Создаёт заёмщика в портфеле, указанном в portfolioId.
Запрос
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Тело:
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
id | строка UUID | да | Идентификатор платформы, задаваемый вызывающей стороной. |
portfolioId | строка UUID | да | Портфель-владелец; должен существовать в вашей организации. |
externalId | string | да | 1-255 символов; уникален для (portfolio, externalId) среди действующих строк. |
name | string | null | нет | Полное имя заёмщика. Сохраняется как есть; чтения для инвесторов маскируют его. |
email | string | null | нет | Email по RFC 5322; сохраняется как есть; чтения для инвесторов маскируют его. |
phone | string | null | нет | Телефон в свободной форме; сохраняется как есть; чтения для инвесторов маскируют его. |
nationalIdLast4 | string | null | нет | Ровно четыре цифры; начальные цифры никогда не возвращаются. |
countryCode | string | null | нет | Двухбуквенный код ISO-3166 (заглавными буквами). |
dob | строка даты | null | нет | YYYY-MM-DD. |
gender | enum | null | нет | male | female | non_binary | other | undisclosed (без учёта регистра). |
incomeBand | string | null | нет | Свободная форма. |
employmentStatus | string | null | нет | Свободная форма. |
metadata | object | null | нет | Дословная сквозная передача. |
Ответы
201 Created при новой записи, 200 OK при идемпотентном повторе:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| Статус | Конверт | Условие |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key совпал с предыдущим запросом; новой записи нет. |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | Вставлена новая строка. |
400 Bad Request | fieldErrors | Ошибка проверки любого поля тела. |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId не существует или принадлежит другой организации. |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | Действующий заёмщик с тем же id уже существует. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
Читает заёмщика по UUID платформы. Поля PII по умолчанию маскируются; администраторы могут запросить исходные PII с помощью ?unmask=true, что создаёт запись в журнале аудита.
Запрос
| Параметр | Расположение | Обязательный | Ограничение |
|---|---|---|---|
id | path | да | UUID заёмщика в платформе. |
unmask | query | нет | true возвращает исходные PII; только для администраторов. По умолчанию маскирует. |
Ответы
200 OK с маскированной записью заёмщика:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| Статус | Условие |
|---|---|
200 OK | Строка существует в вашей организации. PII возвращаются как есть, если вызывающий — администратор И передан ?unmask=true; иначе PII маскируются. |
400 Bad Request | id не является корректным UUID. |
404 Not Found | Строка не существует, отменена или принадлежит другой организации. |
Маскирование PII применяется к name, email, phone и nationalIdLast4. Поле nationalIdLast4 уже при записи хранит только последние четыре цифры; маскирование при чтении всё равно скрывает их от чтений без прав администратора.
Вызывающий без прав администратора, передавший ?unmask=true, не получает 403 — ответ по-прежнему 200 в маскированном виде, а в журнал аудита записывается отклонённая попытка снять маскирование. Платформа не выдаёт проверку роли как ошибку, потому что маскированный вид — безопасное значение по умолчанию; именно аудиторский след делает попытку видимой для службы безопасности.
Вызывающий-администратор, передавший ?unmask=true, получает исходные PII, а запрос создаёт отдельную запись в журнале аудита о снятии маскирования. Ответ содержит Cache-Control: private, no-store, чтобы промежуточные узлы не кэшировали данные с исходными PII.
POST /api/v1/monitoring/loan/loans
Создаёт кредит для существующего заёмщика в том же портфеле.
Запрос
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
id | строка UUID | да | Идентификатор платформы, задаваемый вызывающей стороной. |
portfolioId | строка UUID | да | Портфель-владелец. |
borrowerId | строка UUID | да | Действующий заёмщик в том же портфеле. |
externalId | string | да | 1-255 символов; уникален в портфеле среди действующих строк. |
predecessorLoanId | строка UUID | null | нет | Задаётся при реструктуризации; указывает на заменяемый кредит. |
principalAmount | десятичная строка | да | До четырёх знаков после запятой. |
currencyCode | string | да | Трёхбуквенный ISO-4217; без учёта регистра. |
interestRateApr | десятичная строка | да | До шести знаков после запятой; должно быть >= 0. |
disbursementDate | строка даты | да | YYYY-MM-DD. |
termMonths | integer | да | Должно быть > 0. |
repaymentFrequency | enum | да | monthly | weekly | biweekly | quarterly | bullet (без учёта регистра). |
productType | string | null | нет | Свободная форма, например "Term loan", "Overdraft". |
status | enum | да | pending | active | paid_off | restructured | written_off | defaulted (без учёта регистра). |
metadata | object | null | нет | Дословная сквозная передача. |
Ответы
201 Created (или 200 OK при идемпотентном повторе) с { id, externalId, bronzeSubmissionId, reused }.
| Статус | Конверт | Условие |
|---|---|---|
200 OK | { ..., reused: true } | Идемпотентный повтор. |
201 Created | { ..., reused: false } | Вставлен новый кредит. |
400 Bad Request | fieldErrors | Ошибка проверки (например, отрицательный interestRateApr, некорректный currencyCode). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Портфель отсутствует или принадлежит другой организации. |
409 Conflict | { error, code: "ID_CONFLICT" } | Действующий кредит с тем же id уже существует. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId не указывает на действующего заёмщика в том же портфеле. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
Фиксирует фактический платёж по существующему кредиту. Используйте для полученных платежей, частичных платежей и списаний. Реструктуризация моделируется как новый кредит с заданным predecessorLoanId, а не как платёж.
Запрос
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
id | строка UUID | да | Идентификатор платформы, задаваемый вызывающей стороной. |
portfolioId | строка UUID | да | Портфель-владелец. |
loanId | строка UUID | да | Действующий кредит в том же портфеле. |
externalId | string | да | 1-255 символов; уникален в портфеле среди действующих строк. |
paymentDate | строка даты | да | YYYY-MM-DD. |
amount | десятичная строка | да | Общая сумма полученного платежа. |
currencyCode | string | да | ISO-4217. |
principalPaid | десятичная строка | нет | По умолчанию "0". |
interestPaid | десятичная строка | нет | По умолчанию "0". |
feesPaid | десятичная строка | нет | По умолчанию "0". |
writeOffAmount | десятичная строка | нет | По умолчанию "0". См. правило прощения долга ниже. |
paymentNotes | string | null | нет | Должно равняться "Forgiven" (без учёта регистра), если writeOffAmount > 0. |
paymentMethod | enum | null | нет | cash | bank_transfer | card | mobile_money | check | other. |
metadata | object | null | нет | Дословная сквозная передача. |
Правило прощения долга. Если writeOffAmount > 0, paymentNotes должно равняться "Forgiven" без учёта регистра. Платформа отклоняет запрос на границе API, поэтому некорректный платёж отклоняется до того, как что-либо будет зафиксировано.
Ответы
201 Created (или 200 OK при идемпотентном повторе) с { id, externalId, bronzeSubmissionId, reused }.
| Статус | Конверт | Условие |
|---|---|---|
200 OK | { ..., reused: true } | Идемпотентный повтор. |
201 Created | { ..., reused: false } | Вставлен новый платёж. |
400 Bad Request | fieldErrors | Ошибка проверки (некорректные суммы, несовпадение с перечислением, отсутствует обязательное поле). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Портфель отсутствует или принадлежит другой организации. |
409 Conflict | { error, code: "ID_CONFLICT" } | Действующий платёж с тем же id уже существует. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId не указывает на действующий кредит в том же портфеле. |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | Правило прощения долга сработало при сохранении платежа (редко; проверка данных отклоняет такой же формат раньше). |
GET /api/v1/monitoring/loan/payments/{id}
Читает фактический платёж по UUID платформы, включая отменённые (мягко удалённые) строки. Используйте для проверки записи или просмотра отменённой записи.
Запрос
| Параметр | Расположение | Обязательный | Ограничение |
|---|---|---|---|
id | path | да | UUID платежа в платформе. |
Ответы
200 OK с полной записью платежа. У отменённых строк заполнено deletedAt; у действующих — deletedAt: null. 404 Not Found для чужой организации или неизвестного UUID. 400 Bad Request, если id не является корректным UUID.
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
Переводит кредит в новый статус. Сегмент пути {loanRef} принимает либо UUID кредита в платформе, либо его externalId. Если вы передаёте externalId, необходимо также указать ?portfolioId=<UUID>, потому что внешние идентификаторы не уникальны между портфелями.
Запрос
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Тело:
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
status | enum | да | Одно из active | paid_off | defaulted | written_off | restructured (без учёта регистра). |
effectiveDate | строка даты | да | YYYY-MM-DD. |
reason | string | null | нет | 1-500 символов; записывается в журнал аудита. |
Матрица переходов статуса
Платформа применяет матрицу переходов; недопустимый переход возвращает 422 INVALID_STATUS_TRANSITION с fieldErrors, где названы исходное и целевое состояния.
| Из | Допустимые цели |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (конечный) |
defaulted | written_off, restructured |
written_off | (конечный) |
restructured | (конечный) |
Когда вы переводите кредит в restructured, естественный следующий шаг — POST /loans для заменяющего кредита с заданным predecessorLoanId. Эти две записи намеренно не атомарны — если POST заменяющего кредита завершится ошибкой, предшественник останется в restructured, и интерфейс сверки покажет расхождение при следующем запросе.
Ответы
200 OK при успехе:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| Статус | Конверт | Условие |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | Переход применён (или идемпотентный повтор с reused: true). |
400 Bad Request | fieldErrors | Ошибка проверки тела, отсутствует portfolioId при поиске по externalId, некорректное значение перечисления. |
404 Not Found | { error, code: "NOT_FOUND" } | Кредит не найден по UUID или (portfolioId, externalId) ни на что не указывает. |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | Пары «из/в» нет в матрице переходов; в fieldErrors[].message перечислены допустимые цели. |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | Idempotency-Key уже использован для другого перехода. Предыдущая запись остаётся в силе; отправьте новый переход с новым ключом. |
Переданное вами значение effectiveDate записывается вместе с отправкой и в журнал аудита; в теле ответа оно не возвращается. metadata на этом маршруте намеренно не принимается — сам переход является событием аудита, а необязательное поле reason несёт понятный человеку контекст.
POST /api/v1/monitoring/loan/payments/{id}/cancel
Мягко удаляет ранее зафиксированный платёж. Эндпоинт отмены — единственный интерфейс сторнирования в кредитном домене: PATCH /loans/{id}/adjust нет и не будет.
Запрос
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/jsonТело (необязательное):
| Поле | Тип | Обязательное | Ограничение |
|---|---|---|---|
reason | string | null | нет | 1-500 символов; записывается в событие аудита отмены. |
Пустое тело допускается; заголовок Content-Type можно не передавать вовсе.
Ответы
200 OK при успехе:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}При повторном вызове для того же платежа формат ответа идентичен, за исключением alreadyCancelled: true, а deletedAt содержит исходную отметку времени отмены. Флаг reused отражает состояние идемпотентности, а alreadyCancelled — была ли строка изменена этим вызовом.
| Статус | Конверт | Условие |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | Первая или последующая отмена. |
400 Bad Request | fieldErrors | id не является корректным UUID, или reason длиннее 500 символов. |
404 Not Found | { error, code: "NOT_FOUND" } | Платёж не существует или принадлежит другой организации. |
Запись об отправке создаётся при каждой отмене — включая повторную — для полноты аудита. Строка изменяется только при первом вызове.
Мягкое удаление и повторное использование externalId
Отменённый платёж освобождает свой externalId для повторного использования при будущей записи, потому что ограничение уникальности действует только для действующих строк. Канонический способ исправить ошибочную отправку:
POST /api/v1/monitoring/loan/payments/{id}/cancelдля исходной строки.POST /api/v1/monitoring/loan/paymentsдля новой строки с исправленными полями. Можно повторно использовать тот жеexternalId;idдолжен быть другим.
Так задумано: отмены не разрушают данные (исходная строка сохраняется для аудита), а повторное использование externalId сохраняет пространство операционных идентификаторов вызывающей стороны плотным для целей сверки.