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

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

Базовий 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. Для інтеграції використовуйте повний шлях з /api/v2/.

Авторизація

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

Authorization: ApiKey ВАШ_API_КЛЮЧ

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

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

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

Content-Type: application/json

Більшість методів API працює через POST, навіть якщо метод тільки повертає список. Окремі службові методи можуть використовувати GET; перед використанням звіряйтеся зі сторінкою Усі методи API.

Публічні та службові методи

У QUINCEFIN є клієнтські API-методи й службові endpoint-и для внутрішніх сценаріїв або інтеграцій.

На сторінці Усі методи API методи позначені як:

public - метод виглядає як клієнтський API і може бути кандидатом для публічної документації;
internal - метод належить до службових, BI, test, tracker, admin або integration namespace і не має обіцятися клієнтам без окремого продуктового рішення.

Якщо для методу немає окремої статті, не вважайте його стабільним контрактом тільки через наявність endpoint-а в індексі.

Пагінація

Для багатьох 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 або акаунт, для якого виконувався запит.

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

Як читати індекс методів

Сторінка Усі методи API генерується з фактичних model.json у QFin _apiv2.

Вона корисна для аудиту розривів між кодом і документацією:

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