BimpДовідка

Склад через API: оприбуткування, рухи й обороти, номенклатура

Оновлено 14 хв читання

На цій сторінці
Коротко

Через API Bimp можна оприбуткувати товар (inventoryPosting/api-create), отримати складські рухи за період (inventory/api-readMovements) й обороти з початковим і кінцевим залишком (inventory/api-readTurnovers), створити склад (warehouse/api-create) і завантажити до 500 товарів одним запитом (nomenclature/api-createBatch). Переміщення між компаніями одного акаунта в API немає: це списання в одній компанії й оприбуткування в іншій.

Що будуємо

Складська інтеграція: WMS, система виробництва чи облікова програма оприбутковує товар у Bimp, створює склади й номенклатуру, а назад забирає рухи й обороти за період. Нижче — методи API для цих задач. Усі запити — POST на https://app.bimpsoft.com/org2/... з токеном компанії в заголовку access-token (Початок роботи з API). Логіка документів в інтерфейсі описана в статтях Оприбуткування товарів і Списання запасів.

ЗадачаМетод
Створити, змінити, прочитати оприбуткуванняinventoryPosting: api-create, api-update, api-read, api-readList, api-cancel
Переміщення між складами (з товарами в api-read)movementOfInventories: api-create, api-update, api-read, api-readList, api-cancel
Рухи по складу за періодinventory/api-readMovements
Обороти й залишки за періодinventory/api-readTurnovers
Створити, змінити, прочитати складwarehouse: api-create, api-update, api-read, api-readList
Створити багато товарів одним запитомnomenclature/api-createBatch
Прочитати списання з видом операції й рахунком списанняwriteOffOfInventories/api-read
Знайти списання за організацією й періодомwriteOffOfInventories/api-readList
Знайти компонування за організацією й періодомproduction-assembly/api-readList
Знайти переміщення, створені із замовлення на виробництвоproduction-order/api-read, поле movements
Рахунки для рядків переміщення «Собівартість» і рахунку списанняaccounts/api-readList

Поточні залишки для сайту читає інший метод — inventory/api-readList, див. Вивантаження залишків і цін на сайт.

Як оприбуткувати товар через API

inventoryPosting/api-create створює документ «Оприбуткування запасів» — надходження товару без постачальника: надлишки після інвентаризації, повернення, внесення залишків. Обов’язкові поля: organization (організація), incomeItem (стаття доходів) і масив products. Для кожного рядка обов’язкові nomenclature, warehouse, quantity і price; необов’язкові — project і lineOfBusiness. Шапка може містити number, date, comment, responsible.

curl -X POST https://app.bimpsoft.com/org2/inventoryPosting/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<organization-uuid>",
    "incomeItem": "<income-item-uuid>",
    "date": "2026-11-10T09:00:00",
    "comment": "Надлишок за інвентаризацією 10.11",
    "products": [
      { "nomenclature": "<product-uuid>", "warehouse": "<warehouse-uuid>", "quantity": 12, "price": 140 },
      { "nomenclature": "<product-2-uuid>", "warehouse": "<warehouse-uuid>", "quantity": 3, "price": 860.5 }
    ]
  }'

Відповідь містить uuid створеного документа. Склад задається в кожному рядку, тому одне оприбуткування може класти товар на кілька складів. price — ціна за одиницю: api-read повертає її як суму рядка, поділену на кількість, з округленням до двох знаків. quantity має бути більше нуля: рядок із нулем або від’ємним значенням дає помилку 4xx, і документ не створюється.

Довідкові значення беруть із organization/api-readList, incomeItems/api-readList, warehouse/api-readList, project/api-readList і lineOfBusiness/api-readList.

Як змінити, знайти і скасувати оприбуткування

inventoryPosting/api-update приймає uuid документа і ті самі поля, що й api-create; organization, incomeItem і products у ньому теж обов’язкові. Метод надсилає документ повністю: передані рядки products замінюють усі наявні, а не об’єднуються з ними. Тому передавайте документ повністю, з усіма рядками. Так само діють date, responsible, number і comment: якщо їх не передати, дата документа стане поточною, а відповідальним стане користувач API. Спершу прочитайте документ через api-read і передайте ці поля з нього.

inventoryPosting/api-read за uuid повертає шапку і рядки products з тими самими полями. inventoryPosting/api-readList повертає total і rows (uuid, number, date, comment, archived, sum, organization, incomeItem, responsible) з пагінацією pagination (offset, count до 100). Фільтри передаються в об’єкті filters:

ФільтрЗначення
dateПеріод ["від", "до"] у ISO 8601; верхню межу можна замінити null
organization, incomeItems, responsibleМасиви uuid
number, commentРядок
sumДіапазон суми [мін, макс], будь-яка межа може бути null
showArchivedtrue — показати й архівні документи

inventoryPosting/api-cancel з uuid скасовує документ.

Як перемістити товар між складами і прочитати переміщення

movementOfInventories/api-create створює документ Переміщення запасів між складами однієї компанії. Обов’язкові поля: author, fromWarehouse (склад-відправник), toWarehouse (склад-отримувач) і operationType — 0 «На склад», 1 «В дорозі», 2 «Собівартість». Необов’язкові: status (0 — завершено, 1 — заявка), number, name, date, comment, organization, project, lineOfBusiness, responsibleSender, responsibleReceiver, baseDocument, processing, counterparty і масив products.

Кожен рядок products — це nomenclature і count; необов’язкові unitOfMeasurement, invoice (замовлення покупця, під яке переміщується товар), project, lineOfBusiness, expenseItem і account. Останні два потрібні для виду операції «Собівартість», див. нижче.

curl -X POST https://app.bimpsoft.com/org2/movementOfInventories/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "<employee-uuid>",
    "fromWarehouse": "<warehouse-kyiv-uuid>",
    "toWarehouse": "<warehouse-lviv-uuid>",
    "operationType": 0,
    "products": [
      { "nomenclature": "<product-uuid>", "count": 15 },
      { "nomenclature": "<product-2-uuid>", "count": 4 }
    ]
  }'

Переміщення «Собівартість». Вид operationType: 2 переміщує товар не для зберігання, а для накопичення витрат: собівартість збирається на статті й рахунку витрат, а потім розподіляється документом «Розподіл витрат». Тому кожен рядок products має містити два поля:

ПолеЩо означаєЗвідки взяти
expenseItemСтаття витратexpenseItems/api-readList
accountРахунок витрат, зазвичай 23 «Незавершене виробництво» або 25accounts/api-readList з фільтром { "codes": ["23", "25"] }

accounts/api-readList повертає масив { uuid, code, name }, відсортований за кодом, — той самий список рахунків, що в полі «Рахунок витрат» переміщення в застосунку. Без codes метод повертає всі рахунки.

curl -X POST https://app.bimpsoft.com/org2/movementOfInventories/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "<employee-uuid>",
    "fromWarehouse": "<warehouse-kyiv-uuid>",
    "toWarehouse": "<warehouse-production-uuid>",
    "operationType": 2,
    "products": [
      {
        "nomenclature": "<product-uuid>",
        "count": 5,
        "expenseItem": "<expense-item-uuid>",
        "account": "<account-23-uuid>"
      }
    ]
  }'

Якщо хоча б в одному рядку немає expenseItem або account, документ не створюється, а API повертає 400 з номером рядка. Для operationType 0 і 1 ці поля необов’язкові. В api-update перевірка та сама: якщо передано products без operationType, рядки перевіряються за видом операції, що вже стоїть у документі.

movementOfInventories/api-update приймає uuid і лише ті поля, що змінюються, включно з products. Якщо products передано, воно замінює всі рядки документа; порожній масив products: [] очищає рядки; якщо products не передано, рядки лишаються як були. Окремого методу видалення рядка немає: прочитайте документ через api-read, приберіть рядок і передайте решту.

Товари в api-read. movementOfInventories/api-read за uuid повертає шапку документа (number, date, comment, archived, operationType, status, fromWarehouse, toWarehouse, author, organization, processing, counterparty) і масив products у порядку рядків документа:

ПолеЩо означає
uuid, nameТовар; для модифікації — uuid і назва модифікації
countКількість
unitOfMeasurementОдиниця виміру
invoiceЗамовлення покупця
project, lineOfBusinessПроєкт, напрям діяльності
expenseItem, accountСтаття витрат і рахунок витрат рядка (для «Собівартості»)

Необов’язкові поля рядка приходять лише тоді, коли вони заповнені в документі. Зверніть увагу: у запиті товар передається полем nomenclature, а у відповіді api-read — полем uuid. Документ без товарів повертає products: [].

movementOfInventories/api-readList повертає rows і total без товарів. У filters доступні date (період ["від", "до"]), fromWarehouse, toWarehouse, organization, author (масиви об’єктів { "uuid": "..." }), operationType і status (масиви { "uuid": <число> }), name, comment і showArchived. movementOfInventories/api-cancel з uuid скасовує переміщення. У рухах по складу переміщення дає два рядки з типом movementOfInventories: витрату на складі-відправнику і прихід на складі-отримувачі.

Як прочитати списання

writeOffOfInventories/api-read за uuid повертає документ «Списання запасів»: шапку (number, date, comment, organization, author, responsible, expenseItem, invoiceForCustomerPayment, sum) і рядки products (nomenclature, warehouse, quantity, sum, project, lineOfBusiness). Окрім них, відповідь містить два поля шапки:

ПолеЩо означає
operationType«Вид операції» документа — числовий код; null, якщо поле не заповнене
writeOffAccount«Рахунок списання» — uuid рахунку з accounts/api-readList; null, якщо поле не заповнене

writeOffOfInventories/api-readList повертає об’єкт: total — кількість документів, що відповідають фільтрам, і rows — документи запитаної сторінки, від нових до старих (uuid, number, date, comment, organization, author, expenseItem, sum). Товарів у списку немає, за ними викликайте api-read. Фільтр date — період [початок, кінець): початок входить, кінець ні; кінець можна передати як null.

Як пройти ланцюжок «Компонування → Замовлення на виробництво → Переміщення»

Документи виробництва посилаються один на одного, тож за першим документом можна знайти решту:

  1. production-assembly/api-read повертає компонування з полем productionOrder — uuid замовлення на виробництво.
  2. production-order/api-read повертає замовлення з полем movements — масивом uuid переміщень, створених із цього замовлення, від нових до старих. Якщо переміщень немає, масив порожній.
  3. movementOfInventories/api-read за кожним uuid повертає переміщення з товарами.
curl -X POST https://app.bimpsoft.com/org2/production-order/api-read \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "<production-order-uuid>" }'

Фрагмент відповіді:

{
  "success": true,
  "data": {
    "uuid": "<production-order-uuid>",
    "number": "9",
    "movements": ["<movement-uuid>"]
  }
}

У movements потрапляють переміщення, у яких поле «Замовлення» вказує на це замовлення на виробництво: так документ заповнюється, коли переміщення створюють на підставі замовлення. Скасоване переміщення лишається в списку, помічене на видалення — ні.

Список компонувань production-assembly/api-readList фільтрує документи в об’єкті filters: organization — масив uuid організацій, date — період [початок, кінець), кінець можна передати як null.

curl -X POST https://app.bimpsoft.com/org2/production-assembly/api-readList \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "offset": 0, "count": 100 },
    "filters": {
      "organization": ["<organization-uuid>"],
      "date": ["2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z"]
    }
  }'

Як отримати рухи по складу за період

inventory/api-readMovements повертає рядки складських рухів за період: кожен прихід і кожну витрату по кожному документу, складу й номенклатурі. Обов’язкові period і pagination.

curl -X POST https://app.bimpsoft.com/org2/inventory/api-readMovements \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "period": ["2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z"],
    "warehouseUuids": ["<warehouse-uuid>"],
    "documentTypes": ["purchaseInvoice", "salesInvoice", "writeOffOfInventories"],
    "pagination": { "offset": 0, "count": 100 }
  }'
  • period — [початок, кінець): початок входить у період, кінець — ні. Для жовтня передайте 2026-10-01 і 2026-11-01.
  • warehouseUuids, nomenclatureUuids — необов’язкові фільтри. Фільтр за номенклатурою включає її модифікації.
  • documentTypes — лише рухи цих типів документів: purchaseInvoice, enteringOpeningBalances, inventoryPosting, receivingForSale, productionAssembly, productionDisassembly, productionTask, salesInvoice, cashRegisterReceipt, refundFromCustomer, writeOffOfInventories, putUnderAccounting, refundSupplier, movementOfInventories, transferForSale, reportForSale, extraExpenses, pieceworkSalary, expensesDistribution.

Відповідь — масив, упорядкований за датою. Один рядок — один документ, склад, номенклатура і напрям руху:

ПолеЩо означає
dateДата руху (UTC)
documentuuid, number і type документа
warehouseuuid і name складу
nomenclatureuuid, name і parent — для модифікації батьківський товар, інакше null
quantityКількість: додатна — прихід, від’ємна — витрата
costСума за собівартістю з тим самим знаком, що й quantity, округлена до 2 знаків

Переміщення між складами дає два рядки: витрату на складі-відправнику і прихід на складі-отримувачі. Читайте сторінки, поки відповідь не стане коротшою за count.

Як отримати обороти й залишки за період

inventory/api-readTurnovers рахує для кожної пари «склад — номенклатура» залишок на початок, обороти і залишок на кінець періоду. Цифри збігаються зі звітом Рух товарів. Обов’язкові dateFrom, dateTo (формат YYYY-MM-DD, обидві дати включно) і pagination; фільтри warehouseUuids і nomenclatureUuids — як у рухах.

curl -X POST https://app.bimpsoft.com/org2/inventory/api-readTurnovers \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-10-01",
    "dateTo": "2026-10-31",
    "pagination": { "offset": 0, "count": 100 }
  }'

Кожен рядок містить warehouse, nomenclature і два однакові блоки: quantity (у кількості) та cost (у собівартості):

ПолеЩо входить
openingЗалишок на початок dateFrom
receiptПрихід: надходження, введення залишків, оприбуткування, повернення від покупців, прийом на реалізацію, виробництво
saleПродаж: видаткові накладні, чеки, звіти про продаж
writeOffСписання: списання запасів, витрата у виробництві, повернення постачальнику, прийняття до обліку
transferСальдо переміщень між складами й передачі на реалізацію: від’ємне у відправника, додатне в отримувача
closingЗалишок на кінець dateTo = opening + receipt − sale − writeOff + transfer

У відповідь потрапляють лише склади, що мають залишок або рух у періоді.

Хто бачить рухи, обороти й собівартість

Обидва методи — inventory/api-readMovements і inventory/api-readTurnovers — вимагають у користувача API права на формування звіту «Рух товарів». Повертаються лише склади, до яких користувач має доступ (Доступ співробітника лише до певних складів). Якщо користувач не має доступу до собівартості товарів, поле cost приходить як null, а кількості повертаються.

Як створити склад через API

warehouse/api-create вимагає лише name. Необов’язкові поля:

ПолеЩо означає
mainОсновний склад
active, archivedАктивний, архівний
publicWarehouseПублічний склад
typeТип складу (число): 2 — група складів (папка в ієрархії, не місце зберігання), будь-яке інше значення — звичайний склад. Поле можна передавати в api-create і api-update
address, commentАдреса, коментар
parentБатьківський склад (uuid) для ієрархії
lineOfBusiness, priceList, cashRegister, responsible, counterpartyНапрям діяльності, прайс-лист, каса, відповідальний, контрагент (uuid)
curl -X POST https://app.bimpsoft.com/org2/warehouse/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Склад Львів", "address": "м. Львів, вул. Городоцька, 120", "parent": "<parent-warehouse-uuid>" }'

Відповідь містить uuid нового складу. warehouse/api-update приймає uuid і лише ті поля, що змінюються (включно з name). warehouse/api-read повертає всі поля, а також code і predefined (системний склад) — їх через API задати не можна. warehouse/api-readList повертає uuid, name, main; фільтр main: true залишає лише основний склад. Як склади працюють в інтерфейсі — Склади і магазини.

Як створити багато товарів одним запитом

nomenclature/api-createBatch приймає масив items — від 1 до 500 товарів з тими самими полями, що й nomenclature/api-create. Поля товару, модифікації й поле integration описані в статті Синхронізація каталогу товарів.

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-createBatch \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "goods", "name": "Фарба фасадна 10 л", "article": "FF-10", "unitOfMeasurementUuid": "<unit-uuid>" },
      { "type": "goods", "name": "Фарба фасадна 5 л", "article": "FF-5", "unitOfMeasurementUuid": "<unit-uuid>" },
      { "type": "goods", "name": "Фарба фасадна 10 л", "article": "FF-10B", "unitOfMeasurementUuid": "<unit-uuid>" }
    ]
  }'

Кожна позиція перевіряється як в api-create. Позиція з помилкою не створюється, але решта створюються. Відповідь:

{
  "created": 2,
  "failed": 1,
  "results": [
    { "index": 0, "uuid": "<product-uuid>" },
    { "index": 1, "uuid": "<product-2-uuid>" },
    { "index": 2, "errors": [{ "message": "Номенклатура з такою назвою: «Фарба фасадна 10 л» вже є в цьому запиті (позиція 0)." }] }
  ]
}

results іде в порядку items, index — позиція в масиві з нуля. Збережіть пару «ваш ID — uuid» для кожної успішної позиції, а позиції з errors виправте і надішліть повторно. Типові помилки позиції:

  • Назва вже існує в базі або повторюється в запиті. Назва порівнюється без урахування регістру й пробілів на краях; модифікації ця перевірка не стосується.
  • Інтеграцію не знайдено. У integration.system передано uuid, якого немає в компанії.
  • Вичерпано ліміт товарів тарифу. Позиції понад ліміт отримують помилку 402 (Payment Required), позиції в межах ліміту створюються по порядку.

Для створених товарів надсилається вебхук product_upsert, як і при api-create (Вебхуки).

Як перемістити товар між компаніями акаунта

Переміщення між компаніями одного акаунта в API не підтримується: документ «Переміщення запасів» працює лише між складами однієї компанії. Передачу між компаніями роблять двома запитами з токенами двох компаній (/org2/auth/api-selectCompany для кожної):

  1. Компанія-відправник — writeOffOfInventories/api-create: organization, expenseItem (стаття витрат з expenseItems/api-readList) і products, де для кожного рядка обов’язкові nomenclature, warehouse, quantity, project і lineOfBusiness.
  2. Компанія-отримувач — inventoryPosting/api-create з тими самими кількостями. Якщо передачу треба оформити як закупівлю в іншої компанії, використайте purchaseInvoice/api-create (Закупівлі через API).
# 1. Списання в компанії-відправнику
curl -X POST https://app.bimpsoft.com/org2/writeOffOfInventories/api-create \
  -H "access-token: $SENDER_COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<sender-organization-uuid>",
    "expenseItem": "<expense-item-uuid>",
    "comment": "Передача в компанію-отримувач",
    "products": [
      { "nomenclature": "<sender-product-uuid>", "warehouse": "<sender-warehouse-uuid>", "quantity": 20,
        "project": "<sender-project-uuid>", "lineOfBusiness": "<sender-line-of-business-uuid>" }
    ]
  }'

# 2. Оприбуткування в компанії-отримувачі
curl -X POST https://app.bimpsoft.com/org2/inventoryPosting/api-create \
  -H "access-token: $RECEIVER_COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<receiver-organization-uuid>",
    "incomeItem": "<income-item-uuid>",
    "comment": "Отримано від компанії-відправника",
    "products": [
      { "nomenclature": "<receiver-product-uuid>", "warehouse": "<receiver-warehouse-uuid>", "quantity": 20, "price": 140 }
    ]
  }'

Що врахувати:

  • Uuid у кожній компанії свої. Товари, склади й організації компанії-отримувача мають інші uuid, ніж у відправника. Зіставляйте товари за артикулом (фільтр article у nomenclature/api-readList) або через зовнішні ID з однаковим externalId в обох компаніях.
  • Ціна оприбуткування. Собівартість списання можна взяти з inventory/api-readMovements відправника: рядок документа writeOffOfInventories містить cost і quantity, ціна за одиницю — cost / quantity (обидва від’ємні).
  • Збій між кроками. Якщо списання створено, а оприбуткування — ні, повторіть лише другий крок. Щоб знайти незавершені передачі, writeOffOfInventories/api-readList фільтрує списання за organization (масив uuid) і date (період ["від", "до"]); також доступні expenseItems, author, comment і sum.

Типові помилки

Оприбуткування не створюється, помилка в quantity. Причина: кількість у рядку дорівнює нулю або від’ємна. Рішення: передавайте лише додатні кількості; для зменшення залишку використовуйте списання.

У рухах або оборотах немає частини складів. Причина: користувач API має доступ лише до певних складів. Рішення: розширте доступ користувачу або працюйте з токеном користувача, який бачить усі склади.

cost завжди null. Причина: користувач API не має права бачити собівартість. Рішення: надайте це право в налаштуваннях доступу.

Рухи за місяць пропускають останній день. Причина: кінець period у inventory/api-readMovements не входить у період. Рішення: передавайте першу дату наступного місяця. В inventory/api-readTurnovers, навпаки, dateTo включно.

Переміщення «Собівартість» не створюється, помилка 400 про expenseItem і account. Причина: з operationType: 2 у рядку products немає статті витрат або рахунку. Рішення: передайте обидва поля в кожному рядку; рахунок візьміть з accounts/api-readList.

Помилка 429. Перевищено ліміт запитів, див. Ліміти, пагінація і помилки.

Часті питання

Як оприбуткувати товар на склад через API без документа закупівлі?

Викличте inventoryPosting/api-create: організація, стаття доходів і масив products, де для кожного рядка вказано nomenclature, warehouse, quantity (більше нуля) і price.

Як отримати обороти по складу за місяць, як у звіті «Рух товарів»?

Викличте inventory/api-readTurnovers з dateFrom і dateTo у форматі YYYY-MM-DD (обидві дати включно). Для кожної пари «склад — номенклатура» метод повертає початковий залишок, прихід, продаж, списання, переміщення і кінцевий залишок.

Скільки товарів можна створити одним запитом?

До 500 у nomenclature/api-createBatch. Кожна позиція перевіряється як в api-create; позиція з помилкою не створюється, але не зупиняє інші.

Як перемістити товар з однієї компанії акаунта в іншу через API?

Окремого методу немає. Зробіть два запити з токенами двох компаній: writeOffOfInventories/api-create у компанії-відправнику та inventoryPosting/api-create (або purchaseInvoice/api-create) у компанії-отримувачі.

Як знайти переміщення, створені із замовлення на виробництво?

Викличте production-order/api-read: поле movements містить uuid переміщень, створених із цього замовлення, від нових до старих. Кожне переміщення читається методом movementOfInventories/api-read.

Як створити переміщення з видом операції «Собівартість» через API?

Передайте в movementOfInventories/api-create operationType 2, а в кожному рядку products — expenseItem (стаття витрат з expenseItems/api-readList) і account (рахунок витрат з accounts/api-readList, зазвичай 23 або 25). Без цих двох полів хоча б в одному рядку API поверне помилку 400.

Стаття допомогла?

Читайте далі

Не знайшли відповідь?Напишіть нам — підтримка відповідає в робочий час.