Контрагенты и экономический контекст

Журнал записывает суммы, а контрагенты и метаданные записывают смысл — кто на другой стороне и зачем была операция. Этот слой превращает сырые движения средств в бизнес-события, по которым можно строить отчёты.

Контрагент — это набор адресов

Контрагент — именованная сущность с привязанными адресами. Имя уникально в рамках Vault'а, а каждый адрес принадлежит максимум одному контрагенту — иначе сопоставление было бы неоднозначным. Сети адресов проверяются по реестру Networks.

• POST /api/v1/vaults/{code}/counterparties — создать контрагента (можно сразу с адресами).
• POST /api/v1/vaults/{code}/counterparties/{id}/addresses — добавить адрес.
• GET /api/v1/vaults/{code}/counterparties — список с фильтрами search (подстрока в имени) и kind (например, exchange).

Автосопоставление и ретро-матч

Когда операция идёт на известный адрес или с него, она автоматически привязывается к контрагенту — вручную размечать не нужно. А если адрес добавлен позже, срабатывает ретро-матч: уже существующие операции с этим адресом сопоставляются контрагенту задним числом, а история классификации сохраняется.

Группы контрагентов

Контрагентов можно объединять — например, по типу или юрисдикции:

• POST /api/v1/vaults/{code}/counterparty-groups — создать группу (члены добавляются отдельно). Мутация гейтится политикой counterparty_group_create: при требовании подписи вернётся заявка.

Архивация: история не теряется

Контрагента не удаляют, а архивируют:

• POST /api/v1/vaults/{code}/counterparties/{id}/archive — archived=true: контрагент перестаёт матчиться на новые операции и недоступен для новых переводов, но история сохраняется; false — вернуть. Гейтится политикой counterparty_archive.

Категории операций

Категории — это настраиваемый версионируемый справочник, по которому собираются отчёты и фильтры:

• GET /api/v1/vaults/{code}/operation-categories — список категорий Vault'а. Схема видна любому участнику (из неё собирают categoryKey, groupByField, metricField для конструктора отчётов); viewScope ограничивает доступ к значениям на операциях, а не к самой схеме.

У категории могут быть свои аппруверы (POST / DELETE /api/v1/vaults/{code}/operation-categories/{id}/approvers) — так операции определённой категории могут требовать подтверждения назначенных людей (см. Аппрувалы).

Метаданные операции

Метаданные привязывают к операции её бизнес-контекст:

• GET / PATCH /api/v1/vaults/{code}/operations/{type}/{id}/metadata — upsert плоских метаданных: paymentPurpose, category (валидируемый код из справочника), tags, description, внешние референсы и бизнес-связи (dealId / invoiceId / orderId / settlementId / obligationId). Каждое изменение инкрементирует version.

Связи операций

Операции можно явно связывать друг с другом, чтобы отразить экономическую связь:

• POST /api/v1/vaults/{code}/operation-relations — refund, reversal, correction, replacement. Встречный платёж не считается возвратом автоматически — связь указывается явно; частичный возврат — через relatedAmountRaw.

Как эти связи сочетаются с неизменяемостью журнала — на странице Журнал (двойная запись).

Что дальше