Як отримати PDF-звіт результатів тестування через API

Коротка відповідь

Endpoint GET /api/v1/tests/reports/pdf повертає PDF-звіт з результатами тестування за uniqueId. У query потрібно передати uniqueId, а lang можна передати для вибору мови PDF-звіту. Перед видачею PDF сервер перевіряє, що звіт належить поточній компанії.

Який endpoint використовується?

Використовується GET /api/v1/tests/reports/pdf. Endpoint повертає binary PDF file за унікальним ідентифікатором звіту з тестування.

Параметр	Значення
Method	GET
Endpoint	`/api/v1/tests/reports/pdf`
Base URL	`https://smartway.pro`
Auth	`Bearer token`

Для чого використовується цей API endpoint?

Endpoint використовується для завантаження або відкриття PDF-звіту тестування. Його застосовують після отримання uniqueId зі списку звітів з тестування.

Які передумови потрібні перед виконанням запиту?

Потрібен Bearer token з company context.
Token має містити scope tests.read.
Потрібен uniqueId звіту з тестування, що належить поточній компанії.

Передумова	Опис	Обов’язково
`access_token`	Bearer token з company context	Так
`tests.read`	Scope для читання звітів з тестування	Так
`uniqueId`	Унікальний ідентифікатор звіту з тестування	Так

Які параметри потрібно передати в запиті?

Headers

Header	Тип	Обов’язково	Опис
`Authorization`	string	Так	Bearer token у форматі `Bearer <access_token>`
`Accept`	string	Так	`application/pdf`

Path parameters

Path parameters відсутні.

Query parameters

Параметр	Тип	Обов’язково	Опис
`uniqueId`	string	Так	Унікальний ідентифікатор звіту з тестування
`lang`	string	Ні	Мова PDF-звіту; default `en`, доступні мови `uk`, `ru`, `en`

Request body

Request body не використовується.

curl приклад

curl -X GET 'https://smartway.pro/api/v1/tests/reports/pdf?uniqueId=abc12345&lang=uk' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/pdf' \
  --output test-report-abc12345.pdf

Яку відповідь повертає API?

Успішний запит повертає 200 OK і binary PDF file. Успішна відповідь має Content-Type: application/pdf і Content-Disposition: inline; filename=test-report-<uniqueId>.pdf.

JSON response body не використовується, оскільки відповідь є binary PDF file.

Що означають поля у відповіді API?

Недостатньо даних для опису полів відповіді.

Що відбувається під капотом?

Перед видачею PDF сервер перевіряє, що звіт належить поточній компанії.
Для доступу потрібен scope tests.read.

Які edge cases потрібно врахувати?

Сценарій	Поведінка API	Що зробити інтегратору
`uniqueId` не знайдено	API повертає `404 Not Found`	Перевірити `uniqueId` зі списку звітів з тестування
Звіт не належить поточній компанії	API повертає `404 Not Found`	Використовувати лише `uniqueId`, доступні в tenant-контексті поточної компанії
`lang` не передано	API використовує `en`	Передати `lang`, якщо потрібна інша мова PDF

Які помилки може повернути API?

HTTP status	Опис
`401 Unauthorized`	Відсутній або невалідний Bearer token
`403 Forbidden`	Недостатньо прав
`404 Not Found`	Звіт не знайдено або він не належить поточній компанії
`500 Internal Server Error`	Неочікувана помилка
`503 Service Unavailable`	Збій сервісу

Як використовувати результат у наступних API-запитах?

Значення uniqueId береться з відповіді POST /api/v1/tests/reports/search. Результат PDF-запиту потрібно зберігати у файл або відкривати як PDF-документ.

Приклад отримання uniqueId зі списку звітів:

curl -X POST 'https://smartway.pro/api/v1/tests/reports/search?lang=uk' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 0,
    "size": 20,
    "view": "all"
  }'

Яких помилок інтегратору варто уникати?

Передавати uniqueId, який не належить поточній компанії.
Не вказувати Accept: application/pdf.
Очікувати JSON-відповідь замість binary PDF file.
Викликати endpoint без scope tests.read.

FAQ

Який параметр обов’язковий?

Обов’язковий query parameter uniqueId.

Яку мову PDF можна запитати?

Параметр lang підтримує uk, ru, en; якщо його не передати, використовується en.

Що повертає API?

API повертає binary PDF file з Content-Type: application/pdf.

Що буде, якщо звіт не належить компанії?

API поверне 404 Not Found.

Який scope потрібен?

Для доступу потрібен scope tests.read.

Appearance

Language