Фотографії документів

Під час роботи оператор ТСД може додати до документа фотографії — пошкоджену упаковку, розбіжність, стан товару. Ваша облікова система забирає ці знімки окремим запитом, по одному, коли вони справді потрібні.

Фотографії є в обох видів документів — Перерахунок і Надходження. Механіка для них однакова, відрізняється лише адреса. Базова адреса, конверт відповіді й авторизація — ті самі, що в усьому інтеграційному API (див. «З чого почати»).

Як це влаштовано

Самі зображення в документ не вкладаються — інакше вивантаження роздувалося б до десятків мегабайтів. Тому забирання фото — це два кроки:

Крок 1

photos_thumbnails

за документом — мініатюри, імена й підписи, не вивантажуючи його

Крок 2

download_photo

за іменем забираєте оригінал у base64

Дізнатися, які фотографії є в документа, можна двома способами. Основний — ендпойнт photos_thumbnails: він відразу повертає мініатюри, тому ви показуєте прев'ю, не вивантажуючи ні документ, ні оригінали. Додатково список знімків (без мініатюр) є й у відповіді download — у полі photos[], якщо ви й так забираєте результат.

Список мініатюр

POST /recounts/photos_thumbnails мініатюри фото перерахунку

POST /receipts/photos_thumbnails мініатюри фото надходження

За ідентифікатором документа (external_id) повертає масив усіх його фотографій: ім'я оригіналу, ім'я мініатюри, підпис оператора і саму мініатюру в base64. Рівно те, що потрібно, щоб показати оператору галерею прев'ю й дати вибрати, який знімок відкрити в повному розмірі — без вивантаження документа й важких оригіналів.

Запит

{ "external_id": "INV-2026-0042" }

Відповідь

{
  "ok": true,
  "photos": [
    { "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4",
      "thumb_name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4.thumb",
      "comment": "Стелаж 4, розкрита упаковка",
      "thumb_b64": "/9j/4AAQSkZJRgABAQ…" }
  ]
}

Поле	Що означає
name	Ідентифікатор оригіналу. Його передаєте в `download_photo`, щоб отримати повне фото.
thumb_name	Ідентифікатор мініатюри — ім'я оригіналу з суфіксом `.thumb`.
comment	Підпис оператора.
thumb_b64	Мініатюра (JPEG) у base64. Порожній рядок, якщо мініатюри у знімка немає.

У документа без фотографій photos — порожній масив. Якщо документа з таким external_id немає або він іншого виду (див. «Прив'язка до виду документа» нижче) — відповідь { "ok": false, "error": "not_found" }.

Отримання файлу

POST /recounts/download_photo одне фото перерахунку

POST /receipts/download_photo одне фото надходження

Повертає оригінал однієї фотографії в base64. Ім'я беріть із відповіді photos_thumbnails (або з photos[] в download) того самого документа. Фото віддається по одному — відповідь не розростається, і ви тягнете тільки те, що справді потрібно.

Запит

{ "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4" }

Відповідь

{
  "ok": true,
  "name": "181467df-d4ca-4e4b-b344-1aca7bbb9fb4",
  "comment": "Стелаж 4, розкрита упаковка",
  "size": 148213,
  "data_b64": "/9j/4AAQSkZJRgABAQ…"
}

Поле	Що означає
name	Ідентифікатор знімка — той самий, що ви запросили.
comment	Підпис оператора.
size	Розмір оригіналу в байтах.
data_b64	Сам файл (JPEG), закодований у base64.

Відмова — фото не знайдено

{ "ok": false, "error": "not_found" }

Прив'язка до виду документа

Обидва ендпойнти прив'язані до виду документа так само, як вивантаження. Фотографії перерахунку доступні лише через /recounts/…, фотографії надходження — лише через /receipts/…. Якщо подати external_id перерахунку в /receipts/photos_thumbnails (або ім'я його знімка в /receipts/download_photo), відповідь буде not_found — рівно як і сам документ іншого виду не вивантажиться не через свою адресу.

not_found приходить у трьох випадках: знімка з таким іменем немає, він належить документу іншого виду, або файл уже видалено з сервера. Для вас усі три однакові — фотографії за цим іменем не буде.

Фотографії документів

Як це влаштовано

Список мініатюр

Отримання файлу

Прив'язка до виду документа

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