# Номенклатура (товари та послуги): методи API Bimp

URL: https://bimpsoft.com/help/developers/api-reference/nomenclature/

Методи API Bimp для ресурсу «Номенклатура (товари та послуги)» (`/org2/nomenclature/…`): 15 методів. Базова адреса: `https://app.bimpsoft.com`. Усі запити, крім входу, передають токен компанії в заголовку `access-token` — див. [Початок роботи з API](/help/developers/api-getting-started/).

| Метод | Що робить |
|---|---|
| [`POST /org2/nomenclature/api-readLeftovers`](#api-read-leftovers) | Get the leftovers of nomenclatures on a specific date or the change in leftovers for a specific period |
| [`POST /org2/nomenclature/api-readStocks`](#api-read-stocks) | Get leftovers, reserves and available goods for warehouses on a specific date or change in leftovers for a specific period |
| [`POST /org2/nomenclature/api-readPrices`](#api-read-prices) | Get nomenclature prices on a specific date or price changes over a specific period |
| [`POST /org2/nomenclature/api-primeCost`](#api-prime-cost) | Get nomenclature prime cost by uuid |
| [`POST /org2/nomenclature/api-readList`](#api-read-list) | A request to view a list of nomenclatures |
| [`POST /org2/nomenclature/api-readBatch`](#api-read-batch) | Get a single nomenclature batch by uuid |
| [`POST /org2/nomenclature/api-readBatches`](#api-read-batches) | Get nomenclature batches |
| [`POST /org2/nomenclature/api-create`](#api-create) | A request to create a new nomenclature |
| [`POST /org2/nomenclature/api-update`](#api-update) | A request to update information for an existing nomenclature |
| [`POST /org2/nomenclature/api-saveExternalId`](#api-save-external-id) | Creates or updates the mapping between a nomenclature item and an external system ID (e.g., marketplace SKU or website product ID). |
| [`POST /org2/nomenclature/api-readExternalId`](#api-read-external-id) | Retrieves the external system ID for a specific nomenclature item given the source system name. |
| [`POST /org2/nomenclature/api-readByExternalId`](#api-read-by-external-id) | Identifies a nomenclature item by its external system ID. Returns null if no mapping exists. |
| [`POST /org2/nomenclature/api-readExternalIdsList`](#api-read-external-ids-list) | Retrieves a paginated list of existing mappings with optional filtering by source or nomenclature item. |
| [`POST /org2/nomenclature/api-readWithoutExternalId`](#api-read-without-external-id) | Retrieves a list of nomenclature items that do not have a mapping for the specified source system. |
| [`POST /org2/nomenclature/api-deleteExternalId`](#api-delete-external-id) | Removes the mapping for a specific nomenclature item. If source is omitted, deletes all external mappings for this nomenclature. |

## api-readLeftovers

`POST /org2/nomenclature/api-readLeftovers`

Get the leftovers of nomenclatures on a specific date or the change in leftovers for a specific period

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string |  |
| `[].name` | string |  |
| `[].leftover` | null \| number |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readLeftovers' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## api-readStocks

`POST /org2/nomenclature/api-readStocks`

Get leftovers, reserves and available goods for warehouses on a specific date or change in leftovers for a specific period

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `warehouseUuid` | string (uuid)[] |  | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `nomenclatureUuid` | string (uuid)[] |  | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].nomenclatureUuid` | string (uuid) |  |
| `[].nomenclatureName` | string |  |
| `[].stock` | number |  |
| `[].article` | string |  |
| `[].sku` | string |  |
| `[].groupUuid` | string (uuid) |  |
| `[].groupName` | string |  |
| `[].reserve` | number |  |
| `[].leftover` | number |  |
| `[].minimumLeftover` | number |  |
| `[].maximumLeftover` | number |  |
| `[].primeCost` | number |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readStocks' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"pagination":{"offset":0,"count":10}}'
```

## api-readPrices

`POST /org2/nomenclature/api-readPrices`

Get nomenclature prices on a specific date or price changes over a specific period

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string |  |
| `[].name` | string |  |
| `[].priceLists` | null \| object[] |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readPrices' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## api-primeCost

`POST /org2/nomenclature/api-primeCost`

Get nomenclature prime cost by uuid

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) |  |
| `[].primeCost` | number | A numerical value representing the cost of the product |
| `[].currency` | object |  |
| `[].currency.uuid` | null \| string (uuid) |  |
| `[].currency.iso` | null \| string |  |
| `[].currency.symbol` | null \| string |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-primeCost' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## api-readList

`POST /org2/nomenclature/api-readList`

A request to view a list of nomenclatures

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `parentUuid` | string (uuid) |  | Read modifications of given parent |
| `nomenclatureUuids` | string (uuid)[] |  | Select only nomenclatures with given uuids |
| `created` | object[] |  | Date in the format 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-05-16T09:17:49'). |
| `updated` | object[] |  | Date in the format 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-05-16T09:17:49'). |
| `name` | string |  | Nomenclature name |
| `nameContains` | string |  | Partial search by name |
| `code` | string |  |  |
| `article` | string |  | Nomenclature article |
| `integration` | object |  | The object is filled in for integration search |
| `integration.system` | string (uuid) | так | The integration system through which the element was created |
| `integration.externalId` | string | так | Unique element code from the integration system |
| `nomenclatureGroupUuids` | string (uuid)[] |  | A unique identifier for the Nomenclature group, obtainable from the /nomenclature-group/api-readList request |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) | A unique uuid key of the nomenclature |
| `[].name` | string | Nomenclature name |
| `[].fullName` | string | Nomenclature full name |
| `[].code` | string |  |
| `[].uktzedCode` | string | Product code by UKTZED/DKPP used in tax invoices |
| `[].article` | string | Nomenclature article |
| `[].sku` | string | Nomenclature barcode |
| `[].group` | string (uuid) \| null | A unique identifier for the Nomenclature group, obtainable from the /nomenclature-group/api-readList request |
| `[].supplier` | string (uuid) \| null | A unique identifier for a counterparty of type 'isSupplier'. You can retrieve this UUID using the /counterparty/api-readList request |
| `[].unitOfMeasurementUuid` | string (uuid) | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `[].isKit` | boolean |  |
| `[].type` | string ("goods") \| string ("service") |  |
| `[].isParent` | boolean |  |
| `[].isModification` | boolean | Is this nomenclature a modification? |
| `[].parent` | string (uuid) \| null |  |
| `[].expenseAccount` | string |  |
| `[].description` | string | Nomenclature description |
| `[].comment` | string | An optional text field for any additional notes or comments related to the document |
| `[].picture` | string | Nomenclature picture |
| `[].VATaccounted` | boolean | Parameter that add VAT to the nomenclature from company settings |
| `[].measurements` | object |  |
| `[].measurements.height` | number | height is indicated in centimeters |
| `[].measurements.length` | number | length is indicated in centimeters |
| `[].measurements.width` | number | width is indicated in centimeters |
| `[].measurements.weight` | number | weight is indicated in kilograms |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readList' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"pagination":{"offset":0,"count":10}}'
```

## api-readBatch

`POST /org2/nomenclature/api-readBatch`

Get a single nomenclature batch by uuid

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `uuid` | string (uuid) | так | A unique uuid key of the nomenclature batch |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `uuid` | string (uuid) |  |
| `name` | string |  |
| `fullName` | string \| null |  |
| `code` | string \| null |  |
| `nomenclatureUuid` | string (uuid) |  |
| `counterpartyUuid` | null \| string (uuid) |  |
| `receiptDate` | null \| string (date-time) |  |
| `quantity` | null \| number |  |
| `shelfLife` | null \| number |  |
| `supplierName` | string \| null |  |
| `price` | null \| number |  |
| `currencyUuid` | null \| string (uuid) |  |
| `barcode` | string \| null |  |
| `serialNumber` | string \| null |  |
| `imei` | string \| null |  |
| `comment` | string \| null |  |
| `externalNomenclatureId` | string \| null |  |
| `externalBatchId` | string \| null |  |
| `archive` | boolean |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readBatch' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"00000000-0000-0000-0000-000000000000"}'
```

## api-readBatches

`POST /org2/nomenclature/api-readBatches`

Get nomenclature batches

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) |  |
| `[].name` | string |  |
| `[].fullName` | string \| null |  |
| `[].code` | string \| null |  |
| `[].nomenclatureUuid` | string (uuid) |  |
| `[].counterpartyUuid` | null \| string (uuid) |  |
| `[].receiptDate` | null \| string (date-time) |  |
| `[].quantity` | null \| number |  |
| `[].shelfLife` | null \| number |  |
| `[].supplierName` | string \| null |  |
| `[].price` | null \| number |  |
| `[].currencyUuid` | null \| string (uuid) |  |
| `[].barcode` | string \| null |  |
| `[].serialNumber` | string \| null |  |
| `[].imei` | string \| null |  |
| `[].comment` | string \| null |  |
| `[].externalNomenclatureId` | string \| null |  |
| `[].externalBatchId` | string \| null |  |
| `[].archive` | boolean |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readBatches' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## api-create

`POST /org2/nomenclature/api-create`

A request to create a new nomenclature

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `uuid` | string (uuid) |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-create' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '"string"'
```

## api-update

`POST /org2/nomenclature/api-update`

A request to update information for an existing nomenclature

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `uuid` | string (uuid) | так | A unique uuid key of the nomenclature |
| `name` | string |  | Nomenclature name |
| `fullName` | string |  | Nomenclature full name |
| `article` | string |  | Nomenclature article |
| `sku` | string |  | Nomenclature barcode |
| `group` | string (uuid) \| null |  | A unique identifier for the Nomenclature group, obtainable from the /nomenclature-group/api-readList request |
| `unitOfMeasurementUuid` | string (uuid) |  | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `expenseAccount` | string |  |  |
| `description` | string |  | Nomenclature description |
| `comment` | string |  | An optional text field for any additional notes or comments related to the document |
| `picture` | string |  | Nomenclature picture |
| `VATaccounted` | boolean |  | Parameter that add VAT to the nomenclature from company settings |
| `measurements` | object |  |  |
| `measurements.height` | number | так | height is indicated in centimeters |
| `measurements.length` | number | так | length is indicated in centimeters |
| `measurements.width` | number | так | width is indicated in centimeters |
| `measurements.weight` | number | так | weight is indicated in kilograms |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-update' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"00000000-0000-0000-0000-000000000000"}'
```

## api-saveExternalId

`POST /org2/nomenclature/api-saveExternalId`

Creates or updates the mapping between a nomenclature item and an external system ID (e.g., marketplace SKU or website product ID).

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `nomenclatureUuid` | string (uuid) | так | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `source` | string | так | Identifier of the external system (e.g., "prom", "rozetka"). The value is case-insensitive and automatically normalized (trimmed and converted to lowercase). |
| `externalId` | string | так | Unique identifier of the nomenclature item in the external system (e.g., product ID on the website or external database key) |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `success` | boolean |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-saveExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"nomenclatureUuid":"00000000-0000-0000-0000-000000000000","source":"string","externalId":"string"}'
```

## api-readExternalId

`POST /org2/nomenclature/api-readExternalId`

Retrieves the external system ID for a specific nomenclature item given the source system name.

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `nomenclatureUuid` | string (uuid) | так | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `source` | string | так | Identifier of the external system (e.g. "prom") to check against. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"nomenclatureUuid":"00000000-0000-0000-0000-000000000000","source":"string"}'
```

## api-readByExternalId

`POST /org2/nomenclature/api-readByExternalId`

Identifies a nomenclature item by its external system ID. Returns null if no mapping exists.

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `source` | string | так | Identifier of the external system (e.g., "prom") to check against. |
| `externalId` | string | так | Unique identifier of the nomenclature item in the external system (e.g., product ID on the website or external database key). |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readByExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"source":"string","externalId":"string"}'
```

## api-readExternalIdsList

`POST /org2/nomenclature/api-readExternalIdsList`

Retrieves a paginated list of existing mappings with optional filtering by source or nomenclature item.

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `source` | string |  | Identifier of the external system (e.g. "prom") to check against. |
| `nomenclatureGuid` | string (uuid) |  | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].nomenclatureUuid` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `[].name` | string |  |
| `[].source` | string |  |
| `[].externalId` | string |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readExternalIdsList' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"pagination":{"offset":0,"count":10}}'
```

## api-readWithoutExternalId

`POST /org2/nomenclature/api-readWithoutExternalId`

Retrieves a list of nomenclature items that do not have a mapping for the specified source system.

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `source` | string | так | Identifier of the external system (e.g. "prom") to check against. |

**Відповідь: поле `data`**

| Поле | Тип | Опис |
|---|---|---|
| `[].nomenclatureUuid` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `[].name` | string |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-readWithoutExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"pagination":{"offset":0,"count":10},"source":"string"}'
```

## api-deleteExternalId

`POST /org2/nomenclature/api-deleteExternalId`

Removes the mapping for a specific nomenclature item. If source is omitted, deletes all external mappings for this nomenclature.

**Тіло запиту (JSON)**

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `nomenclatureUuid` | string (uuid) | так | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `source` | string |  | Identifier of the external system (e.g. "prom") to check against. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/nomenclature/api-deleteExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"nomenclatureUuid":"00000000-0000-0000-0000-000000000000"}'
```

Інтерактивна документація з можливістю надіслати тестовий запит: [https://app.bimpsoft.com/docs](https://app.bimpsoft.com/docs). Специфікація OpenAPI оновлюється разом із Bimp; ця сторінка згенерована з неї автоматично.