QUINCE API. Друковані форми документів
API дозволяє отримати список доступних HTML-друкованих форм збереженого документа та сформувати вибрану форму у PDF або XLSX. Файл повертається у Base64, тому його можна зберегти, відкрити чи передати через меню «Поділитися» мобільного застосунку.
Методи й авторизація
| HTTP-метод і шлях | Призначення |
|---|---|
POST /api/v2/document/common/print_forms | Список доступних форм і профілів для документа. |
POST /api/v2/document/common/print | Отримання одного PDF або XLSX у Base64. |
Для зовнішньої інтеграції використовуйте звичайну авторизацію QUINCE API та JSON:
Authorization: ApiKey ВАШ_API_КЛЮЧ
Content-Type: application/json
Сервер визначає користувача й тенанта з авторизації. Поля TenantId і UserId у тілі запиту не змінюють цей контекст. Заголовки мобільного клієнта також не надають додаткового доступу.
Для документа, форми й профілю використовуйте десяткові рядки ідентифікаторів. Це зберігає точність великих bigint у JavaScript і мобільних клієнтах. Додатні JSON-числа приймаються лише в межах безпечних цілих JavaScript; спеціальне значення профілю -1 можна передавати рядком або числом.
Список доступних форм
Метод: POST /api/v2/document/common/print_forms
{
"documentId": "12345"
}
documentId — обов’язковий ідентифікатор збереженого документа. Приклад відповіді нижче умовний: назви, ідентифікатори та кількість форм залежать від документа й користувача.
{
"success": true,
"data": {
"documentId": "12345",
"canPrint": true,
"forms": [
{
"id": "9001",
"name": "Замовлення",
"isCustom": false,
"formats": ["pdf", "xlsx"],
"enabled": true,
"disabledCode": null,
"disabledReason": null,
"effectiveProfileId": "-1",
"profiles": [
{
"id": "-1",
"name": "Глобальні налаштування",
"scope": "Tenant"
}
]
}
]
}
}
| Поле | Опис |
|---|---|
data.documentId | Ідентифікатор документа як рядок. |
data.canPrint | Чи дозволений друк документа за поточних налаштувань. |
data.forms | Доступні поточному користувачу HTML-форми; масив може бути порожнім. |
forms[].id, forms[].name | Ідентифікатор і назва форми. |
forms[].isCustom | Ознака індивідуальної форми. |
forms[].formats | Підтримувані формати: pdf, xlsx. |
forms[].enabled | Чи виконані передумови для використання форми. |
forms[].disabledCode, forms[].disabledReason | Код і текст причини недоступності форми або null. |
forms[].effectiveProfileId | Профіль, який буде використаний, якщо не передати profileId. |
forms[].profiles | Доступні профілі з полями id, name, scope. |
Форма з enabled: false може вимагати банківський рахунок, знижку або одночасну наявність товарів і послуг. Клієнт може показати її назву та disabledReason, але для отримання файлу потрібно спочатку виконати передумови.
Профіль налаштувань друку
Параметр profileId визначає, які налаштування застосувати до вибраної форми:
| Значення | Поведінка |
|---|---|
Поле відсутнє або null | Перший доступний профіль у порядку пріоритету меню друку. Фактичний вибір повертається у відповіді. |
"-1" | Глобальні налаштування друку тенанта. |
Додатний ідентифікатор з profiles | Саме цей доступний профіль документа або користувача й типу документа. |
Передавайте ідентифікатор з отриманого списку. Недоступний, видалений чи чужий профіль відхиляється з PRINT_PROFILE_UNAVAILABLE; сервер не підмінює його глобальними налаштуваннями.
Отримання PDF або XLSX
Метод: POST /api/v2/document/common/print
{
"documentId": "12345",
"printFormId": "9001",
"format": "pdf",
"profileId": "-1"
}
| Параметр | Обов’язковість | Опис |
|---|---|---|
documentId | Так | Ідентифікатор збереженого документа. |
printFormId | Так | Ідентифікатор форми з print_forms. |
format | Так | pdf або xlsx. |
profileId | Ні | Профіль з отриманого списку або -1 для глобальних налаштувань. |
Один запит формує один файл для одного документа. Для XLSX передайте те саме тіло з "format": "xlsx".
{
"success": true,
"data": {
"fileName": "Замовлення_12345.pdf",
"contentType": "application/pdf",
"base64": "...",
"format": "pdf",
"printFormId": "9001",
"profileId": "-1"
}
}
| Формат | contentType |
|---|---|
application/pdf | |
| XLSX | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
base64 містить тільки закодовані байти, без префікса data:. Декодуйте значення та використайте повернені fileName і contentType для збереження або відкриття файлу. Не записуйте вміст Base64 у журнали застосунку.
Максимальний розмір декодованого файлу — 20 MiB. Рядок Base64 приблизно на третину більший за сам файл; врахуйте це під час обробки відповіді на мобільному пристрої.
XLSX формується з того самого HTML-шаблону, що й PDF, і може відрізнятися за розкладкою. Типи комірок залежать від розмітки шаблону: деякі числові значення можуть бути текстовими, зокрема в поточному шаблоні замовлення.
Права доступу та умови друку
Сервер повторно перевіряє права при отриманні файлу, навіть якщо список форм було завантажено раніше. Перевіряються доступ до документа, його типу й тенанта, тарифні та архівні обмеження, призначення форми користувачу, дозвіл адміністратора й доступність профілю.
Мобільний дозвіл на відповідний розділ перевіряється для всіх викликів цих методів:
| Типи документів | Дозвіл на мобільний розділ |
|---|---|
OUTGOING_ORDER | Продажі. |
INCOME_ORDER, INCOME_INVOICE, INCOME_RETURN_INVOICE, INVOICE_INCOME | Закупівлі. |
INITIAL_BALANCE, INITIAL_MONEY, MONEY_BANK_INCOME, MONEY_BANK_OUTGOING, MONEY_CASH_INCOME, MONEY_CASH_OUTGOING, CURRENCY_EXCHANGE, MONEY_MOVING, SALARY_PAYMENT | Гроші. |
INITIAL_STORE, INVENTORY, STOCKS_MOVE, WRITE_OFF_STORE, OUTGOING_RETURN_INVOICE, MANUFACTURE, SPECIFICATION | Склад. |
INVOICE, OUTGOING_INVOICE | Продажі або Склад — документи доступні у спільних журналах. |
Адміністратори зберігають наявний доступ до мобільних розділів; перевірки доступності форм, профілів та умов друку продовжують діяти. Для неадміністраторів типи документів поза наведеним переліком закриті, доки для них не визначено відповідний розділ.
Список містить тільки призначені користувачу й дозволені адміністратором форми відповідного типу документа, тенанта та національного стандарту. Форми, приховані через обмеження собівартості, режим зарплатного документа чи налаштування зовнішньоекономічної діяльності, не повертаються.
Файл формується зі збережених даних документа. Клієнт вибирає друковану форму, формат і профіль налаштувань. Генерація файлу не змінює стан публікації документа чи профіль за замовчуванням.
Неопубліковані документи
Для друку збереженого неопублікованого документа в налаштуваннях обліку тенанта має бути увімкнено «Дозволити друк неопублікованих документів» (PrintUnFixed). Якщо опцію вимкнено, запит списку форм повертає:
{
"success": true,
"data": {
"documentId": "12345",
"canPrint": false,
"forms": [],
"deniedCode": "PRINT_UNFIXED_DENIED",
"deniedReason": "У налаштуваннях обліку вимкнено дозвіл друку неопублікованих документів."
}
}
Запит файлу такого документа відхиляється з PRINT_UNFIXED_DENIED. Опублікований документ можна друкувати незалежно від цієї опції, якщо інші права й умови виконані. Для ще не збереженого документа файл отримати неможливо.
Помилки та обробка відповіді
Методи повертають бізнес-помилки у вкладеному об’єкті error:
{
"success": false,
"error": {
"code": "PRINT_PROFILE_UNAVAILABLE",
"message": "Профіль друку недоступний."
}
}
Перевіряйте success навіть при HTTP 200. Читайте стабільний код з error.code, а текст — з error.message. Окремо обробляйте HTTP-помилки авторизації та транспорту; їхня відповідь може мати інший формат.
error.code | Значення |
|---|---|
UNAUTHENTICATED | Відсутній авторизований контекст користувача. |
VALIDATION_ERROR | Некоректне тіло запиту, ідентифікатор, профіль або формат. |
NOT_FOUND | Документ не знайдено або недоступний. Причина відмови не розкриває чужих даних. |
PRINT_UNFIXED_DENIED | Налаштування тенанта забороняють друк неопублікованого документа. |
PRINT_FORM_UNAVAILABLE | Форма недоступна для документа, користувача чи тенанта. |
PRINT_PROFILE_UNAVAILABLE | Профіль недоступний. |
PRINT_FORM_DISABLED | Не виконано передумови використання форми. |
PRINT_DENIED | Документ зараз не можна друкувати. |
PRINT_RENDER_FAILED | Файл не вдалося сформувати, він некоректний або перевищує ліміт розміру. |
UNAVAILABLE | Інша серверна помилка операції друку. |
У списку форм disabledCode може окремо містити PRINT_BANK_ACCOUNT_REQUIRED, PRINT_DISCOUNT_REQUIRED або PRINT_PRODUCT_SERVICE_REQUIRED. Вони пояснюють, яких реквізитів чи рядків бракує для друку.
Після зміни документа, прав, профілю або налаштувань обліку попередній список може застаріти. Оновіть його перед повторним вибором форми.
Використання в застосунку
Рекомендований порядок роботи:
- Отримайте доступний документ і збережіть його ідентифікатор як рядок.
- Викличте
print_forms, перевіртеcanPrintі покажіть форми з їхніми причинами недоступності. - Дайте вибрати доступну форму, формат і профіль.
- Викличте
print; перевірте HTTP-статус,successта, за потреби,error.code. - Декодуйте Base64 у файл і передайте його засобам відкриття чи поширення мобільної платформи.