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

URL: https://bimpsoft.com/help/developers/inventory-via-api/
Updated: 2026-11-13

> Через 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](https://bimpsoft.com/help/developers/api-getting-started/)). Логіка документів в інтерфейсі описана в статтях [Оприбуткування товарів](https://bimpsoft.com/help/inventory/stock-posting/) і [Списання запасів](https://bimpsoft.com/help/inventory/write-off/).

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

Поточні залишки для сайту читає інший метод — `inventory/api-readList`, див. [Вивантаження залишків і цін на сайт](https://bimpsoft.com/help/developers/sync-stock-and-prices/).

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

`inventoryPosting/api-create` створює документ «Оприбуткування запасів» — надходження товару без постачальника: надлишки після інвентаризації, повернення, внесення залишків. Обов'язкові поля: `organization` (організація), `incomeItem` ([стаття доходів](https://bimpsoft.com/help/getting-started/income-and-expense-items/)) і масив `products`. Для кожного рядка обов'язкові `nomenclature`, `warehouse`, `quantity` і `price`; необов'язкові — `project` і `lineOfBusiness`. Шапка може містити `number`, `date`, `comment`, `responsible`.

```bash
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`](/help/developers/api-reference/organization/#api-read-list), [`incomeItems/api-readList`](/help/developers/api-reference/income-items/#api-read-list), `warehouse/api-readList`, [`project/api-readList`](/help/developers/api-reference/project/#api-read-list) і [`lineOfBusiness/api-readList`](/help/developers/api-reference/line-of-business/#api-read-list).

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

`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` |
| `showArchived` | `true` — показати й архівні документи |

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

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

`movementOfInventories/api-create` створює документ [Переміщення запасів](https://bimpsoft.com/help/inventory/stock-transfer/) між складами однієї компанії. Обов'язкові поля: `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` ([замовлення покупця](https://bimpsoft.com/help/sales/customer-order/), під яке переміщується товар), `project`, `lineOfBusiness`, `expenseItem` і `account`. Останні два потрібні для виду операції «Собівартість», див. нижче.

```bash
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` переміщує товар не для зберігання, а для [накопичення витрат](https://bimpsoft.com/help/costing/cost-accumulation/): собівартість збирається на статті й рахунку витрат, а потім розподіляється документом «Розподіл витрат». Тому кожен рядок `products` має містити два поля:

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

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

```bash
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` повертає [компонування](https://bimpsoft.com/help/production/assembly/) з полем `productionOrder` — uuid [замовлення на виробництво](https://bimpsoft.com/help/production/production-order/).
2. `production-order/api-read` повертає замовлення з полем `movements` — масивом uuid переміщень, створених із цього замовлення, від нових до старих. Якщо переміщень немає, масив порожній.
3. `movementOfInventories/api-read` за кожним uuid повертає переміщення з товарами.

```bash
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>" }'
```

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

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

У `movements` потрапляють переміщення, у яких поле «Замовлення» вказує на це замовлення на виробництво: так документ заповнюється, коли переміщення створюють [на підставі](https://bimpsoft.com/help/basics/create-based-on/) замовлення. Скасоване переміщення лишається в списку, помічене на видалення — ні.

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

```bash
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`.

```bash
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) |
| `document` | `uuid`, `number` і `type` документа |
| `warehouse` | `uuid` і `name` складу |
| `nomenclature` | `uuid`, `name` і `parent` — для модифікації батьківський товар, інакше `null` |
| `quantity` | Кількість: додатна — прихід, від'ємна — витрата |
| `cost` | Сума за собівартістю з тим самим знаком, що й `quantity`, округлена до 2 знаків |

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

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

`inventory/api-readTurnovers` рахує для кожної пари «склад — номенклатура» залишок на початок, обороти і залишок на кінець періоду. Цифри збігаються зі звітом [Рух товарів](https://bimpsoft.com/help/reports/stock-movement-report/). Обов'язкові `dateFrom`, `dateTo` (формат `YYYY-MM-DD`, обидві дати включно) і `pagination`; фільтри `warehouseUuids` і `nomenclatureUuids` — як у рухах.

```bash
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 права на формування звіту «Рух товарів». Повертаються лише склади, до яких користувач має доступ ([Доступ співробітника лише до певних складів](https://bimpsoft.com/help/access/warehouse-access/)). Якщо користувач не має доступу до собівартості товарів, поле `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) |

```bash
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` залишає лише основний склад. Як склади працюють в інтерфейсі — [Склади і магазини](https://bimpsoft.com/help/inventory/warehouses/).

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

`nomenclature/api-createBatch` приймає масив `items` — від 1 до 500 товарів з тими самими полями, що й `nomenclature/api-create`. Поля товару, модифікації й поле `integration` описані в статті [Синхронізація каталогу товарів](https://bimpsoft.com/help/developers/sync-catalog/).

```bash
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`. Позиція з помилкою не створюється, але решта створюються. Відповідь:

```json
{
  "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` ([Вебхуки](https://bimpsoft.com/help/developers/webhooks/)).

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

Переміщення між компаніями одного акаунта в 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](https://bimpsoft.com/help/developers/purchasing-via-api/)).

```bash
# 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](https://bimpsoft.com/help/developers/api-external-ids/) з однаковим `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.** Перевищено ліміт запитів, див. [Ліміти, пагінація і помилки](https://bimpsoft.com/help/developers/api-limits/).

## FAQ

**Як оприбуткувати товар на склад через 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.
