QUINCE API. Конвенції API

Ця сторінка описує базові правила, які варто враховувати перед роботою з окремими методами QUINCEFIN API.

Вона не замінює документацію конкретного endpoint-а. Якщо окрема стаття методу описує спеціальну поведінку, пріоритет має саме вона.

Базовий URL

Базовий URL для API:

https://app.quincefin.com/api/v2/

Повний endpoint складається з базового URL і шляху методу. Наприклад:

POST https://app.quincefin.com/api/v2/product/list
POST https://app.quincefin.com/api/v2/document/outgoing_invoice/list

У статтях документації можуть зустрічатися скорочені назви на кшталт /api/v2/product/list. Для інтеграції використовуйте повний endpoint з вашим доменом і префіксом /api/v2/.

Авторизація

Кожен запит має містити заголовок Authorization:

Authorization: ApiKey ВАШ_API_КЛЮЧ

Ключ генерується в профілі головного користувача акаунту. Якщо для ключа задані дозволені IP-адреси, запити з інших адрес не будуть проходити.

Формат запиту

Для запитів використовується JSON:

Content-Type: application/json

Більшість методів API працює через POST, навіть якщо метод тільки повертає список. Тому не варто вгадувати HTTP-метод за назвою endpoint-а: звіряйтеся зі сторінкою Усі методи API і статтею конкретної сутності або документа.

Перевірка доступних довідників

Метод: POST /api/v2/common/api_catalog_access

Метод повертає коди довідників, доступні поточному API-ключу з урахуванням тарифу/модулів тенанта та налаштувань доступу користувача, від імені якого видано ключ. Тіло запиту не потрібне.

{
  "success": true,
  "data": {
    "entities": ["C_BANK", "C_CASH_ACCOUNT", "C_COMPANY", "C_CURRENCY", "C_PARTNER", "C_PRODUCT"]
  }
}

Метод перевіряє фіксований список кодів (станом на зараз - до 17: C_PARTNER, C_PERSON, C_PRODUCT, C_SERVICE, C_CASH_ACCOUNT, C_BANK_ACCOUNT, C_CURRENCY, C_BANK, C_COMPANY, C_STORE, C_COMPANY_PERSON, C_PROJECT, C_SEGMENT, C_CASH_FLOW_ITEM, C_PNL_ITEM, C_UNIT, C_PRICE_TYPE) і повертає в entities тільки ті з них, доступ до яких дозволено. Недоступні коди в масиві просто відсутні - це не мапа код -> true/false.

Межі публічного контракту

Публічним контрактом для інтеграції варто вважати тільки те, що описано в документації конкретного методу.

Якщо у відповіді або в коді продукту видно додаткові поля, фільтри чи службову поведінку, не закладайте їх у зовнішню інтеграцію без окремої перевірки. Документований сценарій має вищий пріоритет за випадково знайдену реалізаційну деталь.

Пагінація

Для багатьох list-методів використовується параметр page.

{
  "page": 1
}

У поточних статтях API для списків зазвичай вказаний фіксований розмір сторінки 100 елементів. Якщо конкретна стаття описує іншу поведінку, пріоритет має опис конкретного методу.

Папки довідників

Частина довідників QUINCEFIN має ієрархію папок. Для них діє єдиний контракт, тож інтеграції не потрібно вгадувати поведінку для кожного довідника окремо.

Для кожного такого довідника є окремий метод списку папок за шаблоном <довідник>/folder/list.

Семантика filter.ParentFolder

Той самий фільтр працює і в основних list-методах відповідних довідників. За замовчуванням він обмежує вибірку прямим вмістом однієї папки, а не всім піддеревом. Виняток — товари й послуги, де історично повертається весь вміст піддерева; там поведінку регулює окремий параметр filter.FolderRecursive, описаний у статтях Товари і Послуги.

Щоб обійти дерево повністю, викликайте метод списку папок рекурсивно: спочатку з ParentFolder: null, потім для кожної отриманої папки з її Id.

Поля відповіді методів списку папок

Довідники з папками

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

Довідники без папок, зокрема банки, валюти й курси валют, методів folder/list не мають.

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

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

Ідентифікатори та назви

У більшості методів стабільним посиланням на об’єкт є його Id. Назви (Name) зручні для читання, але вони можуть змінюватися, локалізуватися або повторюватися.

Для add та update окремі методи можуть підтримувати пошук пов’язаних об’єктів за назвою. Це завжди треба перевіряти в статті конкретного методу. Якщо стаття прямо не описує пошук за назвою, передавайте Id.

Дати, час і числа

Передавайте дати, час і числові значення в JSON без локального форматування:

• дати - у форматі, який описаний у конкретному методі;
• суми та кількості - як числа, без пробілів, символів валюти або текстових розділювачів;
• валюти, склади, організації, партнери, рахунки й каси - через відповідні Id, якщо метод не описує іншу схему.

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

Nullable та необов’язкові поля

Необов’язкове поле краще не передавати, якщо воно не потрібне для сценарію. Передавайте null тільки тоді, коли конкретний метод явно підтримує очищення значення через null.

Для update не припускайте, що відсутнє поле автоматично очищає значення. Зазвичай відсутнє поле означає, що інтеграція не намагається його змінити.

list

Методи list повертають список об’єктів або документів. Типові параметри:

• page - номер сторінки;
• фільтри за періодом, організацією, складом, партнером або статусом - якщо вони описані в конкретній статті.

Не використовуйте неописані фільтри як публічний контракт, навіть якщо вони випадково працюють у поточній версії.

add

Методи add створюють новий об’єкт або документ.

Перед викликом add перевірте:

• які поля є обов’язковими;
• чи треба передавати пов’язані об’єкти через Id;
• чи створює метод пов’язані об’єкти автоматично;
• що буде, якщо переданий Id не існує або недоступний користувачу API.

Для документів також перевіряйте, які поля потрібні в рядках документа: товар або послуга, одиниця виміру, кількість, ціна, сума, склад, рахунок або каса.

update

Методи update змінюють наявний об’єкт або документ.

Зазвичай для оновлення потрібен Id об’єкта або документа. Перед інтеграцією уточніть у статті методу:

• чи можна оновлювати проведений документ;
• які поля можна змінювати;
• чи замінюються рядки документа повністю;
• чи можна частково оновлювати окремі поля.

unpublish

Для частини документів є метод unpublish.

unpublish використовується для зняття проведення документа. Після цього рухи, які документ створював у грошах, складах, взаєморозрахунках або управлінських звітах, переглядаються системою відповідно до логіки документа.

Перед використанням unpublish в інтеграції перевірте:

• чи дозволено знімати проведення для потрібного типу документа;
• чи не закритий період;
• чи немає залежних документів або обмежень доступу;
• який наступний крок інтеграції: повторний update, повторне проведення або створення нового документа.

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

Частина довідників QUINCEFIN підтримує єдиний контракт видалення, архівування й відновлення: той самий формат запиту та відповіді працює для кожного довідника зі списку нижче, тож інтеграції не потрібно вгадувати поведінку окремо для кожного з них.

Довідники з уніфікованим контрактом

Партнери й контракти видаляються іншим, окремим механізмом; звіряйтеся зі статтями Партнери і Контракти.

Видалення (markasdelete)

Метод: /api/v2/<довідник>/markasdelete

{
  "array": [
    { "Id": 123 }
  ]
}

Якщо елемент можна видалити фізично - його видаляють. Якщо на нього посилаються інші дані, замість фізичного видалення елемент переводиться в архів (Void = true). Обидва результати вважаються успіхом:

{
  "success": true,
  "data": [
    { "Id": 123, "Deleted": true, "Archived": false, "IsFolder": false }
  ]
}

Відмова:

{
  "success": false,
  "error": "Локалізований текст помилки",
  "code": "SYSTEM_ITEM",
  "data": [ { "Id": 123 } ]
}

Відновлення (restore)

Метод: /api/v2/<довідник>/restore

Той самий формат запиту { "array": [ { "Id": 123 } ] }. Успішна відповідь:

{
  "success": true,
  "data": [
    { "Id": 123, "Restored": true, "IsFolder": false }
  ]
}

Для організацій (/api/v2/company/restore) відновлення поки не реалізоване: метод завжди повертає відмову з кодом NOT_SUPPORTED.

Показ архівних елементів у списках

Методи list для довідників з таблиці вище (і для більшості інших списків) приймають булевий filter.Archive: false - тільки активні елементи (поведінка за замовчуванням), true - тільки архівні, поле відсутнє - без обмеження за архівністю. У відповіді архівність позначена полем Void.

Коди відмов

Такий самий формат { success:false, error, code } повертають і методи add/update для кас і рахунків (/api/v2/cash_account/*) та контрактів (/api/v2/contract/update), коли запит порушує правило незмінності власника, описане нижче.

Незмінність власника (Company/Partner) у підпорядкованих довідниках

Для кас і банківських рахунків (/api/v2/cash_account/*, /api/v2/bank_account/list), а також для контрактів (/api/v2/contract/*), організація (Company) - а для контрактів ще й партнер (Partner) - тепер повертається у списках не скалярним Id, а вкладеним об’єктом:

{
  "Company": { "Id": 10, "Name": "Наше підприємство, ТОВ" }
}

Це зворотно несумісна зміна порівняно з попередньою версією цих методів, де поле передавалося просто числовим Id. Якщо інтеграція раніше читала Company як число, оновіть парсинг на Company.Id.

Разом з об’єктом повертається прапорець блокування:

• CompanyLocked (каси й рахунки) - true, якщо по рахунку вже є рух у грошовому регістрі; спроба змінити Company в такому разі відхиляється з кодом FIELD_LOCKED.
• OwnerLocked (контракти) - true, якщо по контракту вже є документи або взаєморозрахунки; спроба змінити Company або Partner в такому разі відхиляється з кодом FIELD_LOCKED.

Для кас і рахунків поле Company також стало обов’язковим при add/update: запит без Company відхиляється з локалізованою помилкою error і кодом FIELD_REQUIRED.

Документи та рухи

Документи в QUINCEFIN можуть впливати на:

• рух товарів;
• рух грошей;
• взаєморозрахунки з партнерами;
• собівартість;
• Cash Flow, P&L та інші управлінські звіти.

Через це інтеграції з документами треба тестувати не тільки за відповіддю API, а й за результатом у звітах, журналах і пов’язаних списках QUINCEFIN.

Баланси та залишки

У API є кілька різних типів залишків:

• balances/list - залишки взаєморозрахунків із партнерами;
• stock/list - залишки товарів;
• cash_balance/list - залишки грошей.

Не змішуйте ці методи в інтеграції. Вони відповідають на різні бізнес-питання.

Помилки

Формат помилок може залежати від конкретного методу й рівня обробки запиту. Для стабільної інтеграції логування має зберігати:

• endpoint;
• request body без секретних ключів;
• HTTP status;
• response body;
• час запиту;
• tenant або акаунт, для якого виконувався запит.

Це допомагає швидше відрізнити помилку авторизації, помилку доступу, некоректні дані та бізнес-обмеження документа.

Мінімальний сценарій перевірки

Перед запуском інтеграції в робочому середовищі перевірте мінімум такий ланцюжок:

1. Авторизація працює з реальним API-ключем і дозволеною IP-адресою.
2. list повертає очікувані дані на тестовому періоді або тестовому об’єкті.
3. add або update створює очікуваний результат без прихованих побічних ефектів.
4. Документ або об’єкт видно в інтерфейсі QUINCEFIN і він має очікувані значення.
5. Якщо метод працює з документами, перевірений результат у журналах, залишках або звітах.

Як користуватися індексом методів

Сторінка Усі методи API допомагає швидко перейти до потрібного розділу API: компанія, партнери, товари, документи, гроші або залишки.

Найкращий порядок роботи такий:

1. Знайдіть потрібну бізнес-сутність або тип документа.
2. Відкрийте окрему статтю з параметрами, прикладами та форматом відповіді.
3. Перевірте запит на тестовому сценарії перед запуском інтеграції в робочому середовищі.