QUINCE API. Каси

Список методів

Метод	Опис
`/api/v2/cash_account/list`	Отримання списку кас
`/api/v2/cash_account/add`	Створення каси або банківського рахунку
`/api/v2/cash_account/update`	Оновлення каси або банківського рахунку
`/api/v2/cash_account/markasdelete`	Видалення або архівування каси/рахунку
`/api/v2/cash_account/restore`	Відновлення каси/рахунку з архіву
`/api/v2/cash_account/folder/list`	Отримання списку папок рахунків і кас

Отримання списку кас

Назва методу: /api/v2/cash_account/list

Повертає список кас і готівкових рахунків, доступних користувачу API. Для навігації використовується номер сторінки page.

Якщо filter.IsCash не передати, API не обмежує вибірку цим прапором. Для банківських рахунків окремо використовується /api/v2/bank_account/list, де IsCash примусово дорівнює false.

Параметри запиту

Поле	Опис
`filter`	Об’єкт з фільтрами. Необов’язковий.
`filter.Id`	Ідентифікатор каси.
`filter.Company`	Ідентифікатор організації.
`filter.IsCash`	Ознака готівкового рахунку.
`filter.ParentFolder`	Ідентифікатор папки. Якщо поле не передати, обмеження за папкою немає; `null` повертає елементи першого рівня; `Id` повертає прямий вміст папки.
`filter.IsFolder`	Якщо `false`, повертаються тільки каси й рахунки без папок. Якщо `true`, тільки папки. Якщо поле не передати, повертаються і папки, і рахунки.
`filter.Archive`	Ознака архівності.
`filter.MobileApp`	Якщо `true`, API повертає збільшений ліміт елементів для мобільного сценарію.
`page`	Номер сторінки. Необов’язковий.

Поля відповіді

Поле	Опис
`Id`	Ідентифікатор каси.
`Name`	Назва каси.
`Company`	Організація: об’єкт `{ "Id": ..., "Name": ... }`.
`CompanyLocked`	`true`, якщо по касі/рахунку вже є рух у грошовому регістрі. У такому разі зміна `Company` через `/api/v2/cash_account/update` буде відхилена з кодом `FIELD_LOCKED`.
`IsCash`	Ознака готівкового рахунку.
`Currency`	Валюта рахунку: об’єкт `{ "Id": ..., "Code": ... }`.
`CurrencyCode`	Код валюти рахунку (те саме значення, що й `Currency.Code`, для зворотної сумісності).
`Bank`	Банк з довідника банків, якщо обраний: об’єкт `{ "Id": ..., "Name": ... }` або `null`. Зазвичай заповнений тільки для банківських рахунків.
`Iban`	IBAN, якщо застосовується.
`BankAccount`	Номер рахунку, якщо застосовується.
`BankName`	Назва банку, якщо застосовується (текстове поле; якщо обрано `Bank` з довідника, підтягується з нього).
`BankMFO`	МФО банку, якщо застосовується (текстове поле; якщо обрано `Bank` з довідника, підтягується з нього).
`Memo`	Коментар.
`IsFolder`	Ознака папки.
`ParentFolder`	Ідентифікатор батьківської папки або `null` для першого рівня.
`IsDefault`	Ознака рахунку за замовчуванням.
`Void`	Ознака архівності.

Company повертається об’єктом, а не скалярним Id - це зворотно несумісна зміна. Якщо інтеграція раніше читала Company як число, оновіть парсинг на Company.Id. Детальніше - у розділі Незмінність власника конвенцій API.

Приклад запиту

{
  "filter": {
    "Company": 10,
    "IsCash": true,
    "IsFolder": false,
    "Archive": false
  },
  "page": 1
}

Створення та оновлення кас

Назва методу створення: /api/v2/cash_account/add

Назва методу оновлення: /api/v2/cash_account/update

Ці самі методи створюють і оновлюють як каси, так і банківські рахунки (IsCash розрізняє їх) - окремих методів для /api/v2/bank_account/* немає. Методи приймають один об’єкт рахунку в тілі запиту (не масив). Для оновлення обов’язковий Id.

Company обов’язкове для обох методів: запит без Company відхиляється з локалізованою помилкою error. Зміну Company на іншу організацію заблоковано, якщо по рахунку вже є рух у грошовому регістрі (CompanyLocked: true) - відповідь у такому разі повертає code: "FIELD_LOCKED".

Якщо передати Bank - ідентифікатор банку з довідника банків, - то BankName/BankMFO автоматично підтягуються з обраного банку і перезаписують те, що було передано текстом. Якщо Bank не передавати, BankName/BankMFO зберігаються як звичайний текст.

Параметри запиту

Поле	Опис
`Id`	Ідентифікатор каси/рахунку. Обов’язковий для `/api/v2/cash_account/update`.
`Name`	Назва каси/рахунку. Обов’язкова.
`IsCash`	`true` - каса, `false` - банківський рахунок.
`Company`	Ідентифікатор організації. Обов’язковий.
`Currency`	Ідентифікатор валюти.
`Bank`	Ідентифікатор банку з довідника банків. Необов’язковий.
`BankName`	Назва банку текстом. Перезаписується, якщо переданий `Bank`.
`BankMFO`	МФО банку текстом. Перезаписується, якщо переданий `Bank`.
`Iban`	IBAN.
`BankAccount`	Номер рахунку.
`Memo`	Коментар.

Приклад запиту

{
  "Name": "Каса №1",
  "IsCash": true,
  "Company": 10,
  "Currency": 1
}

Формат відповіді

Успішна відповідь повертає той самий набір полів, що й /api/v2/cash_account/list (включно з Company і CompanyLocked), крім того, що Currency і Bank у відповіді add/update повертаються скалярним Id, а не вкладеним об’єктом, на відміну від list.

{
  "success": true,
  "data": {
    "Id": 501,
    "Name": "Каса №1",
    "IsCash": true,
    "Company": { "Id": 10, "Name": "Наше підприємство, ТОВ" },
    "CompanyLocked": false,
    "CurrencyCode": "UAH",
    "Currency": 1,
    "Bank": null,
    "BankName": null,
    "BankMFO": null,
    "Iban": null,
    "BankAccount": null,
    "Memo": null,
    "Void": false
  }
}

Відмова:

{
  "success": false,
  "error": "Локалізований текст помилки",
  "code": "FIELD_LOCKED"
}

Видалення, архівування та відновлення кас

Каси й банківські рахунки входять до довідників з уніфікованим контрактом видалення й відновлення (/api/v2/cash_account/markasdelete і /api/v2/cash_account/restore, той самий контракт і для папок). Повний опис формату запиту, відповіді та кодів відмов - у розділі Видалення, архівування та відновлення довідників. Непорожню папку видалити не можна - відмова з кодом FOLDER_NOT_EMPTY.

Папки рахунків і кас

Назва методу: /api/v2/cash_account/folder/list

Банківські рахунки й каси зберігають папки в одному довіднику, тому метод списку папок для них спільний. Дерево папок кас і дерево папок банківських рахунків розділяються фільтром filter.IsCash.

Фільтр filter.ParentFolder працює за загальним правилом з розділу Папки довідників.

Параметри запиту

Поле	Опис
`filter.ParentFolder`	Ідентифікатор батьківської папки або `null` для першого рівня. Якщо поле не передати, повертаються всі папки.
`filter.Id`	Ідентифікатор папки.
`filter.IsCash`	`true` - папки кас, `false` - папки банківських рахунків. Якщо не передати, повертаються обидва дерева.
`filter.Archive`	Ознака архівності.
`filter.MobileApp`	Якщо `true`, API повертає збільшений ліміт елементів для мобільного сценарію.
`page`	Номер сторінки. Необов’язковий.

Поля відповіді

Поле	Опис
`Id`	Ідентифікатор папки.
`Name`	Назва папки.
`ParentFolder`	Ідентифікатор батьківської папки або `null` для першого рівня.
`IsCash`	Ознака належності папки до кас.
`Void`	Ознака архівності.

Приклад запиту

{
  "filter": {
    "IsCash": true,
    "ParentFolder": null
  },
  "page": 1
}