QUINCEFINСпробувати
Відкрити меню

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
PDFapplication/pdf
XLSXapplication/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. Вони пояснюють, яких реквізитів чи рядків бракує для друку.

Після зміни документа, прав, профілю або налаштувань обліку попередній список може застаріти. Оновіть його перед повторним вибором форми.

Використання в застосунку

Рекомендований порядок роботи:

  1. Отримайте доступний документ і збережіть його ідентифікатор як рядок.
  2. Викличте print_forms, перевірте canPrint і покажіть форми з їхніми причинами недоступності.
  3. Дайте вибрати доступну форму, формат і профіль.
  4. Викличте print; перевірте HTTP-статус, success та, за потреби, error.code.
  5. Декодуйте Base64 у файл і передайте його засобам відкриття чи поширення мобільної платформи.