Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

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даПортфель-владелец; должен существовать в вашей организации.
externalIdstringда1-255 символов; уникален для (portfolio, externalId) среди действующих строк.
namestring | nullнетПолное имя заёмщика. Сохраняется как есть; чтения для инвесторов маскируют его.
emailstring | nullнетEmail по RFC 5322; сохраняется как есть; чтения для инвесторов маскируют его.
phonestring | nullнетТелефон в свободной форме; сохраняется как есть; чтения для инвесторов маскируют его.
nationalIdLast4string | nullнетРовно четыре цифры; начальные цифры никогда не возвращаются.
countryCodestring | nullнетДвухбуквенный код ISO-3166 (заглавными буквами).
dobстрока даты | nullнетYYYY-MM-DD.
genderenum | nullнетmale | female | non_binary | other | undisclosed (без учёта регистра).
incomeBandstring | nullнетСвободная форма.
employmentStatusstring | nullнетСвободная форма.
metadataobject | 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 RequestfieldErrorsОшибка проверки любого поля тела.
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, что создаёт запись в журнале аудита.

Запрос

ПараметрРасположениеОбязательныйОграничение
idpathдаUUID заёмщика в платформе.
unmaskqueryнет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 Requestid не является корректным 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даДействующий заёмщик в том же портфеле.
externalIdstringда1-255 символов; уникален в портфеле среди действующих строк.
predecessorLoanIdстрока UUID | nullнетЗадаётся при реструктуризации; указывает на заменяемый кредит.
principalAmountдесятичная строкадаДо четырёх знаков после запятой.
currencyCodestringдаТрёхбуквенный ISO-4217; без учёта регистра.
interestRateAprдесятичная строкадаДо шести знаков после запятой; должно быть >= 0.
disbursementDateстрока датыдаYYYY-MM-DD.
termMonthsintegerдаДолжно быть > 0.
repaymentFrequencyenumдаmonthly | weekly | biweekly | quarterly | bullet (без учёта регистра).
productTypestring | nullнетСвободная форма, например "Term loan", "Overdraft".
statusenumдаpending | active | paid_off | restructured | written_off | defaulted (без учёта регистра).
metadataobject | nullнетДословная сквозная передача.

Ответы

201 Created (или 200 OK при идемпотентном повторе) с { id, externalId, bronzeSubmissionId, reused }.

СтатусКонвертУсловие
200 OK{ ..., reused: true }Идемпотентный повтор.
201 Created{ ..., reused: false }Вставлен новый кредит.
400 Bad RequestfieldErrorsОшибка проверки (например, отрицательный 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даДействующий кредит в том же портфеле.
externalIdstringда1-255 символов; уникален в портфеле среди действующих строк.
paymentDateстрока датыдаYYYY-MM-DD.
amountдесятичная строкадаОбщая сумма полученного платежа.
currencyCodestringдаISO-4217.
principalPaidдесятичная строканетПо умолчанию "0".
interestPaidдесятичная строканетПо умолчанию "0".
feesPaidдесятичная строканетПо умолчанию "0".
writeOffAmountдесятичная строканетПо умолчанию "0". См. правило прощения долга ниже.
paymentNotesstring | nullнетДолжно равняться "Forgiven" (без учёта регистра), если writeOffAmount > 0.
paymentMethodenum | nullнетcash | bank_transfer | card | mobile_money | check | other.
metadataobject | nullнетДословная сквозная передача.

Правило прощения долга. Если writeOffAmount > 0, paymentNotes должно равняться "Forgiven" без учёта регистра. Платформа отклоняет запрос на границе API, поэтому некорректный платёж отклоняется до того, как что-либо будет зафиксировано.

Ответы

201 Created (или 200 OK при идемпотентном повторе) с { id, externalId, bronzeSubmissionId, reused }.

СтатусКонвертУсловие
200 OK{ ..., reused: true }Идемпотентный повтор.
201 Created{ ..., reused: false }Вставлен новый платёж.
400 Bad RequestfieldErrorsОшибка проверки (некорректные суммы, несовпадение с перечислением, отсутствует обязательное поле).
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 платформы, включая отменённые (мягко удалённые) строки. Используйте для проверки записи или просмотра отменённой записи.

Запрос

ПараметрРасположениеОбязательныйОграничение
idpathда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>

Тело:

ПолеТипОбязательноеОграничение
statusenumдаОдно из active | paid_off | defaulted | written_off | restructured (без учёта регистра).
effectiveDateстрока датыдаYYYY-MM-DD.
reasonstring | nullнет1-500 символов; записывается в журнал аудита.

Матрица переходов статуса

Платформа применяет матрицу переходов; недопустимый переход возвращает 422 INVALID_STATUS_TRANSITION с fieldErrors, где названы исходное и целевое состояния.

ИзДопустимые цели
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(конечный)
defaultedwritten_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 RequestfieldErrorsОшибка проверки тела, отсутствует 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

Тело (необязательное):

ПолеТипОбязательноеОграничение
reasonstring | 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 RequestfieldErrorsid не является корректным UUID, или reason длиннее 500 символов.
404 Not Found{ error, code: "NOT_FOUND" }Платёж не существует или принадлежит другой организации.

Запись об отправке создаётся при каждой отмене — включая повторную — для полноты аудита. Строка изменяется только при первом вызове.

Мягкое удаление и повторное использование externalId

Отменённый платёж освобождает свой externalId для повторного использования при будущей записи, потому что ограничение уникальности действует только для действующих строк. Канонический способ исправить ошибочную отправку:

  1. POST /api/v1/monitoring/loan/payments/{id}/cancel для исходной строки.
  2. POST /api/v1/monitoring/loan/payments для новой строки с исправленными полями. Можно повторно использовать тот же externalId; id должен быть другим.

Так задумано: отмены не разрушают данные (исходная строка сохраняется для аудита), а повторное использование externalId сохраняет пространство операционных идентификаторов вызывающей стороны плотным для целей сверки.