REST API поставщика ТОВАРНО

Базовый адрес — https://app.moyskladdemo.xyz.

API позволяет агенту поставщика загружать Excel/CSV и проверять результат обработки. Ключ связан с Telegram ID его владельца. Агент получает доступ к документам этого пользователя.

Подключение

1. Откройте бота ТОВАРНО, нажмите «Старт», выберите загрузку документов и роль поставщика или сотрудника.
2. Откройте личный кабинет через Mini App или персональную ссылку из бота.
3. Перейдите в раздел API, задайте понятное название ключа и создайте ключ.
4. Сохраните показанный ключ в секретах своей системы. В кабинете он показывается один раз.
5. При прекращении интеграции отзовите ключ в кабинете.

Передавайте ключ только в заголовке Authorization: Bearer …. Ключ хранится на стороне вашего сервера или агента. В клиентскую веб-страницу и в URL его помещать не следует.

Формат документа

Загрузка принимает файлы XLSX или CSV размером от 1 байта до 100 МиБ — 104 857 600 байт. Исходный файл сохраняется в закрытом хранилище и появляется в журнале с именем файла, автором, Telegram ID, временем и источником.

Для автоматического проведения прямых отгрузок текущая версия полностью обрабатывает таблицу до 20 строк данных. Более крупный документ принимается в журнал и требует проверки перед проведением.

Заголовки должны быть в первой строке. В XLSX используется первый читаемый лист. Для CSV удобен UTF-8 с BOM и разделитель ;. Формулы в таблице требуют проверки.

Обработка

После приёма запускается проверка товаров и документов. Точный артикул или уникальное точное название сопоставляются с каталогом. Сокращения поставщика используются после явного подтверждения соответствия. При неоднозначности документ получает статус needs_review, а бот присылает уведомление.

Уточнить обозначение можно в боте сообщением Уточнить N: название поставщика = НАШ-АРТИКУЛ, где N — номер записи журнала. Для нескольких неизвестных товаров отправляйте уточнения последовательно. Подтверждённые соответствия сохраняются для данного поставщика.

Успешное проведение создаёт приёмки и отгрузки в МоёмСкладе на отдельном складе прямых отгрузок. Закупка образует обязательство перед поставщиком, продажа — задолженность покупателя. Фактические оплаты учитываются отдельными операциями.

Голосовые пояснения доступны через Telegram-бота. Передача аудио через этот REST API пока не предусмотрена.

Загрузка через агента

POST /api/v1/documents

Тело запроса содержит исходные байты файла. Обязательные заголовки приведены ниже.

Пример для Bash. Переменная TOVARNO_API_KEY должна быть заранее передана средой исполнения из секретов вашей системы.

file='./supplier-report.xlsx'
filename=$(python3 -c 'import pathlib,sys,urllib.parse; print(urllib.parse.quote(pathlib.Path(sys.argv[1]).name, safe=""))' "$file")
checksum=$(python3 -c 'import hashlib,sys; print(hashlib.file_digest(open(sys.argv[1],"rb"),"sha256").hexdigest())' "$file")

curl --fail-with-body --silent --show-error \
  'https://app.moyskladdemo.xyz/api/v1/documents' \
  -H "Authorization: Bearer ${TOVARNO_API_KEY}" \
  -H 'Content-Type: application/octet-stream' \
  -H "X-File-Name: ${filename}" \
  -H "X-Content-SHA256: ${checksum}" \
  -H 'Idempotency-Key: warehouse-20261111-report-001' \
  --data-binary "@${file}"

Пример ответа HTTP 201.

{
  "id": 42,
  "filename": "supplier-report.xlsx",
  "status": "received",
  "size": 5821
}

Номер, имя и размер выше приведены как пример. Сохраните реальный id из ответа и проверяйте состояние через метод документа.

Повтор запроса

При потере ответа повторите запрос с тем же Idempotency-Key, тем же именем, размером и содержимым файла. API вернёт HTTP 200 и тот же id, с полем reused: true. Поле status такого ответа отражает приём файла, актуальный результат проведения получите отдельным GET-запросом.

Если для уже использованного идентификатора изменились имя, размер или контрольная сумма, сервер вернёт HTTP 409. Для новой версии файла используйте новый идентификатор. Запрос с неверной контрольной суммой отклоняется с HTTP 422.

При HTTP 5xx или сетевой ошибке используйте ограниченные повторы с задержкой и тем же идентификатором отправки. При HTTP 400, 401, 409, 413, 415 или 422 сначала устраните указанную причину.

Статус документа

GET /api/v1/documents/{id}

document_id=42
curl --fail-with-body --silent --show-error \
  "https://app.moyskladdemo.xyz/api/v1/documents/${document_id}" \
  -H "Authorization: Bearer ${TOVARNO_API_KEY}"

Ответ содержит document — поля записи журнала — и processing — результат обработки или null, пока он отсутствует. Поле document.status содержит актуальный статус. Результат обработки может включать errors, unmatched, totals и ссылки на созданные документы.

Для опроса достаточно интервала 5–10 секунд с ограничением числа попыток. Статус needs_review требует действия человека или исправленного файла. Статус posted завершает проведение.

Список документов

GET /api/v1/documents

curl --fail-with-body --silent --show-error \
  'https://app.moyskladdemo.xyz/api/v1/documents' \
  -H "Authorization: Bearer ${TOVARNO_API_KEY}"

Ответ — { "entries": [...], "counts": {...}, "scope": "own" }. Возвращаются последние 100 записей пользователя, которому принадлежит ключ. API не возвращает закрытые пути хранения.

Ошибки

Управление ключами из кабинета

Эти методы используются интерфейсом кабинета с браузерной сессией или подписанными Telegram initData. Тело — JSON. Доступ ограничен ключами текущего пользователя.

В списке видны название, безопасный префикс и времена создания, последнего использования и отзыва. Времена передаются в секундах Unix. Полное значение ключа возвращается только при создании. На сервере хранится его хеш.

Ключ авторизует загрузку файлов и чтение собственных записей через REST. Уточнения товаров и назначение имён отправителям выполняются через кабинет и Telegram с соответствующими правами.