Загрузка файлов и вложений

В документации мы постарались ответить на частые вопросы по работе TesLab, с которыми сталкиваются пользователи.
Если Вы не нашли ответ на свой вопрос, напишите нам.

Личный кабинет
09 Ноя

Загрузка файлов и вложений

API, интеграция, TesLab, файлы, скачивание, вложения Комментарии

Файл становится вложением после привязки к нужной карточке. Одни методы принимают файл и ID записи одним запросом, другие используют предварительную загрузку и отдельное сохранение. Ниже показаны оба варианта: для диспетчерской заявки обслуживания и для существующей заявки ИЛ.

В этой статье

Выберите способ загрузки

  • Прямое вложение: отправьте файл вместе с ID существующей записи. Пример: maintenance/requests/files/staff/add для вложений сотрудников в диспетчерской заявке.
  • Предварительная загрузка: отправьте файл в system/preloadfile, получите временное имя и передайте его при сохранении карточки поддерживающим это методом.

Предварительная загрузка сама по себе не прикрепляет документ. Прямой staff/add, напротив, ожидает содержимое файла и не принимает вместо него временное имя. Выбирайте вариант по контракту целевой карточки.

Два способа прикрепить файл: прямой multipart-запрос с ID или предварительная загрузка с последующим сохранением карточки.
Это два альтернативных пути. В обоих случаях результатом должна стать связь файла с нужной карточкой.

Что передавать в запросе

ДанныеКак передать
fileФайловая часть multipart-формы с исходным именем и содержимым. Строка с локальным путём или Base64 в JSON её не заменяет.
idВнутренний ID существующей записи, к которой прикрепляется документ. В прямом примере передаётся обычным полем формы.
authЗаголовок с токеном сессии, как и в других запросах API.
Out: jsonЗаголовок для получения ответа в формате JSON.

Для multipart не задавайте Content-Type вручную: curl или браузер сформирует заголовок с правильной границей частей. Заголовок application/json используется во втором шаге привязки, когда передаются параметры карточки без содержимого файла.

Прямое вложение в диспетчерскую заявку

curl 'https://lab.example/api/maintenance/requests/files/staff/add' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Out: json' \
  -F 'id=900701' \
  -F 'file=@/path/to/Акт осмотра.pdf'

При успехе метод возвращает ok, внутреннее имя file, признак миниатюры mini и список вложений сотрудников s_files. Например:

{
  "ok": true,
  "file": "STORED_FILE_EXAMPLE.pdf",
  "mini": false,
  "s_files": [{
    "name": "Акт осмотра",
    "file": "STORED_FILE_EXAMPLE.pdf",
    "date": "2026-11-10 10:00:00",
    "uid": 42,
    "mini": false
  }]
}

name служит подписью документа, file является ключом для последующих операций, date и uid показывают время и автора добавления. В прямом примере подпись формируется из исходного имени без расширения. Условные имена в статье замените значениями из своего ответа.

В JavaScript используйте FormData и проверяйте не только завершение fetch, но и подтверждение нового файла в реестре:

const file = fileInput.files?.[0];
if (!file) throw new Error('Выберите файл');

const form = new FormData();
form.set('id', '900701');
form.set('file', file);

const response = await fetch(
  'https://lab.example/api/maintenance/requests/files/staff/add',
  {method: 'POST', headers: {auth: 'YOUR_AUTH_TOKEN', Out: 'json'}, body: form}
);
let result;
try { result = await response.json(); }
catch { throw new Error('Не удалось прочитать ответ загрузки'); }

const registry = result?.s_files;
const rows = Array.isArray(registry) ? registry
  : registry && typeof registry === 'object' ? Object.values(registry) : [];
if (!response.ok || result?.ok !== true
    || typeof result.file !== 'string' || !result.file
    || !rows.some(row => row?.file === result.file)) {
  throw new Error(result?.mess || result?.title || 'Привязка файла не подтверждена');
}

Для повторного чтения вызовите maintenance/requests/info с тем же id: список находится в files.staff. Файлы заявителя составляют отдельный набор files.users. Скачивание вложения сотрудников выполняется через maintenance/requests/files/staff/download с id и полученным file.

Предварительная загрузка и привязка к заявке ИЛ

  1. Отправьте сам файл multipart-формой в system/preloadfile.
  2. Из успешного ответа возьмите file. Это временное имя, а не ID карточки или постоянный URL.
  3. Передайте имя в целевое сохранение карточки и проверьте результат привязки.
curl 'https://lab.example/api/system/preloadfile' \
  -H 'auth: YOUR_AUTH_TOKEN' \
  -H 'Out: json' \
  -F 'file=@/path/to/Акт осмотра.pdf'

Ответ:
{"ok": true, "file": "TEMP_FILE_EXAMPLE.pdf"}

Для существующей заявки ИЛ второй шаг поддерживает laboratory/requests/edit. Поле attachmentsOnly выделяет изменение вложений; tmpName задаёт подпись, tmpFile указывает временный файл. Ключ обоих объектов в примере совпадает с именем из preload:

POST /api/laboratory/requests/edit
auth: YOUR_AUTH_TOKEN
Out: json
Content-Type: application/json

{
  "id": 501,
  "attachmentsOnly": 1,
  "tmpName": {"TEMP_FILE_EXAMPLE.pdf": "Акт осмотра"},
  "tmpFile": {"TEMP_FILE_EXAMPLE.pdf": "TEMP_FILE_EXAMPLE.pdf"}
}

Успешный ответ содержит ok: true, ID заявки и её данные в res. Полученное имя должно появиться в res.ufiles. Другие карточки могут использовать иной метод или структуру сохранения: этот пример относится именно к заявке ИЛ.

Прикрепляйте временный файл сразу после загрузки. Очистка может удалить его после 20 минут хранения; точный момент зависит от запуска обслуживания сервера. Если файл уже исчез, загрузите его заново. В форме дождитесь окончания загрузки всех файлов перед сохранением.

Типы, размеры и изображения

Общий загрузчик принимает расширения pdf, doc, docx, xls, xlsx, xlsm, ppt, pptx, rtf, odt, ods, odp, txt, csv, jpg, jpeg, png, gif, bmp, webp, tif, tiff, heic, psd, zip, rar, 7z, eml, msg, sig, p7s, mp4, mp3, tl. Проверяется последнее расширение имени без учёта регистра. Допустимое расширение не означает, что содержимое подходит для импорта в любой модуль.

Общего единого размера файла для всех методов нет. Действуют ограничения веб-сервера, PHP и конкретной формы или обработчика. В общий лимит POST входят и файл, и остальные части формы.

В прямом примере изображение может уменьшаться в рамку 1500×1500 с сохранением пропорций. Отдельная миниатюра 300×300 может кадрироваться. Учитывайте обработку изображений, если обмен требует сохранения исходных байтов.

У system/preloadfile предусмотрены дополнительные параметры обработки копии изображения:

  • miniMaxW, miniMaxH: положительные целые размеры в пикселях, не более 10000; по умолчанию 1500.
  • miniQuality: качество от 1 до 100, по умолчанию 60.
  • thumbnail: кадрирование копии под заданные размеры вместо вписывания с сохранением пропорций.

Эти параметры не являются преобразователем любого документа в изображение. Успех загрузки файла не гарантирует наличие миниатюры.

Ошибки загрузки

  • Не приложен файл: проверьте поле file, передачу multipart и ограничения размера запроса.
  • Тип файла отклонён: проверьте последнее расширение и требования целевого метода.
  • Частичная передача или ошибка записи: ориентируйтесь на сообщение сервера; связь с карточкой должна быть подтверждена отдельно.
  • 404: проверьте ID. При превышении общего лимита POST PHP может отбросить и файл, и поле id, поэтому причина иногда связана с размером.
  • 409 или сообщение об изменении списка: обновите вложения карточки перед повтором, чтобы учесть другую завершённую операцию.

HTTP-отказ, неверный JSON и отсутствие подтверждения привязки не являются успешной загрузкой. Для пачки файлов учитывайте результат каждого: часть может сохраниться, а часть завершиться ошибкой.

Повтор после обрыва связи

Если ответ прямого добавления или сохранения карточки потерян, сначала прочитайте её вложения. Сервер мог выполнить операцию до обрыва связи; повторное добавление способно создать дубль. Если файл уже появился, используйте его ключ для дальнейшей работы.

Если потерян только ответ preload, повторная предварительная загрузка создаст новое временное имя. Используйте его в следующем сохранении. Не восстанавливайте постоянный путь или URL из временного имени самостоятельно.

Связанные материалы