Ledger accounts API

API endpoints

Ledger accounts API

Рахунки операційного журналу групують гаманці й облікові операції навколо бізнес-сутності клієнта: користувача, мерчанта, treasury або settlement account.

Операції

MethodPathScopeОпис
GET/api/v1/ledger/accountsaccounts:readСписок рахунків із cursor pagination
POST/api/v1/ledger/accountswallets:createСтворення рахунку
GET/api/v1/ledger/accounts/{accountId}accounts:readЧитання одного рахунку
GET/api/v1/ledger/accounts/{accountId}/walletswallets:readГаманці, прив’язані до рахунку
GET/api/v1/ledger/accounts/{accountId}/balanceswallets:readПроєкції балансів рахунку
GET/api/v1/ledger/accounts/{accountId}/transactionstransactions:readТранзакції рахунку

Створення рахунку

POST /api/v1/ledger/accounts

json
{
  "name": "Treasury",
  "externalId": "customer-4821",
  "metadata": {
"region": "EU"
  }
}

name є обов’язковим. Необов’язковий externalId має містити 1–128 символів і повинен посилатися на стабільний ідентифікатор у вашій системі. metadata — необов’язковий object.

Операція вимагає X-Api-Body-Hash, але поточний Swagger не вимагає X-Idempotency-Key і не декларує fingerprint replay handling. Якщо потрібен бізнес-захист від дублікатів, використовуйте унікальний externalId.

Список і пошук рахунків

GET /api/v1/ledger/accounts приймає cursor, limit, search та externalId. Response містить items і nextCursor.

Деталі рахунку

Response містить id, orgId, name, nullable externalId, nullable metadata, createdAt та updatedAt. Detail endpoint також повертає інформацію рівня рахунку, визначену актуальною схемою.

Конфлікти й ліміти

  • 409 ACCOUNT_EXTERNAL_ID_CONFLICT — зовнішній ідентифікатор уже існує.
  • 422 ACCOUNT_METADATA_TOO_LARGE — metadata перевищує 16 KiB.
  • 404 RESOURCE_NOT_FOUND — рахунок недоступний поточній організації.