Виды операций
type | Строка входа | Scope |
|---|---|---|
inventory.set | Тело установки остатка. | inventory:write |
products.upsert | Тело записи товара по внешнему id, плюс external_id и, если нужна проверка версии, version. | catalog:write |
money_transactions.create | Тело ручного дохода или расхода. | finance:write |
money_transactions.update | Тело правки движения денег, плюс id движения и, если нужна проверка версии, version. Так разносят журнал по статьям пачкой. | finance:write |
orders.export | Входа нет: операция выгружает заказы по фильтрам из params. | orders:read |
libro_iva.export | Входа нет: операция собирает книги Libro IVA Digital юрлица за месяц — в params legal_entity_id, period (YYYY-MM) и books (ventas, compras или обе). | fiscal:read |
accountant_package.export | Входа нет: операция собирает пакет бухгалтера юрлица за месяц — в params legal_entity_id и period. | fiscal:read |
Запуск операции требует bulk:write вдобавок к scope её вида. Каждая строка проходит те же проверки, что одиночный запрос, и получает тот же ответ, поэтому строка с ошибкой не останавливает остальные.
Подготовьте вход
NDJSON — один объект JSON на строку. Файл остатков:
{"variant_id": 1042, "location_id": 3, "on_hand": "24", "expected_on_hand": "20"}
{"variant_id": 1043, "location_id": 3, "on_hand": "0", "expected_on_hand": "5"}
{"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "expected_on_hand": "12.5"}
Файл — до 256 МБ, строка — до 1 МБ; файл, сжатый gzip, распаковывается на входе. Загрузите его частями или дайте операции url файла — магазин скачает его сам.
Загрузка частями
Начните загрузку с именем и размером файла. Ответ сообщает размер части, chunk_bytes, до 1 МБ:
curl -X POST "https://api.saleya.app/v1/uploads" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 3c2b1a09-8f7e-4d6c-b5a4-938271605f4e' \
-H "Content-Type: application/json" \
-d '{
"file_name": "stock-2026-11-11.ndjson",
"size": 3407872
}'HTTP/1.1 201 Created
{
"id": 55,
"file_name": "stock-2026-11-11.ndjson",
"size": 3407872,
"received": 0,
"complete": false,
"chunk_bytes": 1048576,
"expires_at": "2026-11-12T14:30:00Z",
"created_at": "2026-11-11T14:30:00Z"
}Отправляйте файл по порядку, по части за запрос: сырые байты — телом, байт, с которого часть начинается, — в offset. Когда received дойдёт до размера, загрузка complete.
curl -X POST "https://api.saleya.app/v1/uploads/55/chunks?offset=1048576" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928' \
-H "Content-Type: application/octet-stream" \
--data-binary '@stock.part-01'После обрыва связи прочитайте загрузку и продолжайте с received. Часть с другим смещением получает 409 upload_offset_mismatch, и ответ называет верное.
Запуск операции
curl -X POST "https://api.saleya.app/v1/bulk-operations" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 2b1a0f9e-8d7c-4b6a-9594-837261504f3e' \
-H "Content-Type: application/json" \
-d '{
"type": "inventory.set",
"input": {
"upload_id": 55
}
}'Ответ — 202 с операцией и её адресом в Location. Операции приложения идут по одной, в порядке создания; ждать и идти могут до 5 одновременно, ещё одна получает 409 bulk_operation_queue_full.
Следите за ней через GET /bulk-operations/{operation} — status и счётчики lines — или ждите вебхук bulk_operation.finished. Отмена останавливает операцию между двумя строками: записанное остаётся.
Результат
Результат — тоже NDJSON: на каждую строку входа строка с её номером, статусом, который она получила бы отдельным запросом, и ответом — записью или отказом.
{"line": 1, "status": 200, "body": {"status": "applied", "inventory_level": {"variant_id": 1042, "location_id": 3, "on_hand": "24", "reserved": "2", "available": "22", "updated_at": "2026-11-11T14:31:02Z"}}}
{"line": 2, "status": 409, "body": {"type": "stock_on_hand_changed", "title": "On-hand quantity changed", "status": 409, "detail": "The on-hand quantity is 4, not 5: stock moved after it was read. Read the level again and repeat the request with the new expected_on_hand.", "current": {"on_hand": "4"}}}
{"line": 3, "status": 200, "body": {"status": "unchanged", "inventory_level": {"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "reserved": "0", "available": "12.5", "updated_at": "2026-11-10T09:12:44Z"}}}
Результат можно читать, пока операция идёт: он только растёт. Продолжайте скачивание с Range: bytes=<скачано>-. Результат orders.export — сами заказы, а законченная выгрузка отдаёт sync_cursor, чтобы продолжить список заказов.
У libro_iva.export и accountant_package.export результат — не NDJSON, а ZIP с теми же файлами, что выгружает панель магазина. Он появляется целиком, когда операция completed; до этого и у отказавшей операции результат отвечает 409. Если книгу не собрать из-за документов периода, операция заканчивается failed, а error.documents называет каждый документ и причину.
Операция и её файлы хранятся 7 дней после окончания.