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 і статтею конкретної сутності або документа.

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

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

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

Пагінація

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

{
  "page": 1
}

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

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

У більшості методів стабільним посиланням на об’єкт є його 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 можуть впливати на:

• рух товарів;
• рух грошей;
• взаєморозрахунки з партнерами;
• собівартість;
• 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. Перевірте запит на тестовому сценарії перед запуском інтеграції в робочому середовищі.