# Specifications: Bimp API methods

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

Bimp API methods for the “Specifications” resource (`/org2/specification/…`): 4 methods. Base URL: `https://app.bimpsoft.com`. All requests except login pass the company token in the `access-token` header — see [Getting started with the API](/en/help/developers/api-getting-started/).

| Method | What it does |
|---|---|
| [`POST /org2/specification/api-read`](#api-read) | A request to obtain detailed information for a particular specification |
| [`POST /org2/specification/api-readList`](#api-read-list) |  |
| [`POST /org2/specification/api-create`](#api-create) | A request to create a new specification |
| [`POST /org2/specification/api-update`](#api-update) | A request to update the specification |

## api-read

`POST /org2/specification/api-read`

A request to obtain detailed information for a particular specification

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `uuid` | string (uuid) | yes | A unique uuid key for the Specification |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) | A unique uuid key for the Specification |
| `name` | string | Specification name |
| `comment` | string | An optional text field for any additional notes or comments related to the document |
| `cost` | number | A numerical value representing the cost of the product |
| `nomenclature` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `specificationGroup` | string (uuid) | UUID of the specification group |
| `currency` | string (uuid) | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `quantity` | number | The amount of items |
| `composition` | object[] | Specification materials / components |
| `composition[].nomenclature` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].quantity` | number | The amount of items |
| `composition[].price` | number | The price of the item/document |
| `composition[].sum` | number | The sum of the document |
| `composition[].costShare` | number | Cost share |
| `composition[].netQuantity` | number | Net quantity |
| `composition[].loss` | number | Loss percent. Must match ((quantity - netQuantity) / quantity) * 100 when both loss and netQuantity are provided |
| `composition[].uniqueId` | string | Row unique id of the composition line |
| `composition[].relatesTo` | string | uniqueId of the related production stage |
| `composition[].nodeSpecification` | string (uuid) \| null |  |
| `composition[].analogWriteOffMethod` | number | Method of writing off analogs |
| `composition[].rowNumber` | number | Row number in the composition table |
| `composition[].notUsedInProduction` | boolean | Whether the material is not used in production |
| `composition[].analogs` | object[] | Analog nomenclatures for this composition line |
| `composition[].analogs[].nomenclature` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].analogs[].characteristic` | string (uuid) \| null | Characteristic UUID of the analog nomenclature |
| `composition[].analogs[].priority` | number | Analog priority / order |
| `composition[].analogs[].warehouseStock` | number | Available stock of the analog on warehouses |
| `archived` | boolean | Whether the specification is archived |
| `specificationType` | number | Specification type code |
| `costCalculationMethod` | number | Cost calculation method code |
| `createdAt` | string \| null | Specification creation date/time |
| `useAsTemplate` | boolean | Whether the specification is used as a template |
| `useOperationStages` | boolean | Whether production stages and operations are used |
| `version` | string | Specification version |
| `useSemiFinishedProducts` | boolean | Whether semi-finished products are used |
| `nomenclatureType` | number | Nomenclature type code |
| `operationsSum` | number | Total sum of production operations |
| `plannedCost` | number | Planned cost of the specification |
| `productionStages` | object[] | Production stages of the specification |
| `productionStages[].uniqueId` | string | Row unique id of the production stage |
| `productionStages[].stage` | object \| null | Production stage catalog reference |
| `productionStages[].priority` | number | Stage priority / order |
| `productionStages[].quantity` | number | The amount of items |
| `productionStages[].executionTime` | number | Stage execution time |
| `productionStages[].sum` | number | The sum of the document |
| `productionStages[].semiFinishedProduct` | object \| null | Semi-finished product linked to the stage |
| `productionStages[].semiFinishedCharacteristic` | object \| null | Characteristic of the semi-finished product |
| `productionOperations` | object[] | Production operations of the specification |
| `productionOperations[].uniqueId` | string | Row unique id of the production operation |
| `productionOperations[].relatesTo` | string | uniqueId of the related production stage |
| `productionOperations[].technologicalOperation` | object \| null | Technological operation catalog reference |
| `productionOperations[].performer` | object \| null | A unique identifier for the Employee, obtainable from the /employee/api-readList |
| `productionOperations[].contract` | object \| null | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `productionOperations[].executionTime` | number | Operation execution time |
| `productionOperations[].quantity` | number | The amount of items |
| `productionOperations[].price` | number | The price of the item/document |
| `productionOperations[].sum` | number | The sum of the document |
| `productionOperations[].catalogType` | object \| null | Catalog type of the technological operation |
| `operationDependencies` | object[] | Dependencies between production operations |
| `operationDependencies[].uniqueId` | string | uniqueId of the dependent production operation |
| `operationDependencies[].relatesTo` | string | uniqueId of the related preceding operation |
| `operationDependencies[].previousOperation` | string | Previous operation identifier |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/specification/api-read' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"00000000-0000-0000-0000-000000000000"}'
```

## api-readList

`POST /org2/specification/api-readList`

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `pagination` | object | yes |  |
| `pagination.offset` | number | yes | Begin from {offset} elements |
| `pagination.count` | number | yes | Limit of paginated elemets |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].uuid` | string (uuid) | A unique uuid key for the Specification |
| `[].name` | string | Specification name |
| `[].nomenclature` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `[].specificationGroup` | string (uuid) | UUID of the specification group |
| `[].quantity` | number | The amount of items |
| `[].archived` | boolean | Whether the specification is archived |
| `[].specificationType` | number | Specification type code |
| `[].costCalculationMethod` | number | Cost calculation method code |
| `[].createdAt` | string \| null | Specification creation date/time |
| `[].useAsTemplate` | boolean | Whether the specification is used as a template |
| `[].useOperationStages` | boolean | Whether production stages and operations are used |
| `[].version` | string | Specification version |
| `[].useSemiFinishedProducts` | boolean | Whether semi-finished products are used |
| `[].nomenclatureType` | number | Nomenclature type code |
| `[].operationsSum` | number | Total sum of production operations |
| `[].plannedCost` | number | Planned cost of the specification |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/specification/api-readList' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"pagination":{"offset":0,"count":10}}'
```

## api-create

`POST /org2/specification/api-create`

A request to create a new specification

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Specification name |
| `nomenclature` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `quantity` | number | yes | The amount of items |
| `currency` | string (uuid) | yes | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `specificationGroup` | string (uuid) |  | UUID of the specification group |
| `comment` | string |  | An optional text field for any additional notes or comments related to the document |
| `archived` | boolean |  | Whether the specification is archived |
| `specificationType` | number |  | Specification type code |
| `costCalculationMethod` | number |  | Cost calculation method code |
| `useAsTemplate` | boolean |  | Whether the specification is used as a template |
| `useOperationStages` | boolean |  | Whether production stages and operations are used |
| `version` | string |  | Specification version |
| `useSemiFinishedProducts` | boolean |  | Whether semi-finished products are used |
| `nomenclatureType` | number |  | Nomenclature type code |
| `operationsSum` | number |  | Total sum of production operations |
| `plannedCost` | number |  | Planned cost of the specification |
| `productionStages` | object[] |  | Production stages of the specification |
| `productionStages[].uniqueId` | string |  | Row unique id of the production stage |
| `productionStages[].stage` | object \| null |  | Production stage catalog reference |
| `productionStages[].priority` | number |  | Stage priority / order |
| `productionStages[].quantity` | number |  | The amount of items |
| `productionStages[].executionTime` | number |  | Stage execution time |
| `productionStages[].sum` | number |  | The sum of the document |
| `productionStages[].semiFinishedProduct` | object \| null |  | Semi-finished product linked to the stage |
| `productionStages[].semiFinishedCharacteristic` | object \| null |  | Characteristic of the semi-finished product |
| `productionOperations` | object[] |  | Production operations of the specification |
| `productionOperations[].uniqueId` | string |  | Row unique id of the production operation |
| `productionOperations[].relatesTo` | string |  | uniqueId of the related production stage |
| `productionOperations[].technologicalOperation` | object \| null |  | Technological operation catalog reference |
| `productionOperations[].performer` | object \| null |  | A unique identifier for the Employee, obtainable from the /employee/api-readList |
| `productionOperations[].contract` | object \| null |  | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `productionOperations[].executionTime` | number |  | Operation execution time |
| `productionOperations[].quantity` | number |  | The amount of items |
| `productionOperations[].price` | number |  | The price of the item/document |
| `productionOperations[].sum` | number |  | The sum of the document |
| `productionOperations[].catalogType` | object \| null |  | Catalog type of the technological operation |
| `operationDependencies` | object[] |  | Dependencies between production operations |
| `operationDependencies[].uniqueId` | string |  | uniqueId of the dependent production operation |
| `operationDependencies[].relatesTo` | string |  | uniqueId of the related preceding operation |
| `operationDependencies[].previousOperation` | string |  | Previous operation identifier |
| `composition` | object[] |  |  |
| `composition[].nomenclature` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].quantity` | number | yes | The amount of items |
| `composition[].price` | number | yes | The price of the item/document |
| `composition[].sum` | number |  | The sum of the document |
| `composition[].costShare` | number |  | Cost share |
| `composition[].netQuantity` | number |  | Net quantity |
| `composition[].loss` | number |  | Loss percent. Must match ((quantity - netQuantity) / quantity) * 100 when both loss and netQuantity are provided |
| `composition[].uniqueId` | string |  | Row unique id of the composition line |
| `composition[].relatesTo` | string |  | uniqueId of the related production stage |
| `composition[].nodeSpecification` | string (uuid) \| null |  |  |
| `composition[].analogWriteOffMethod` | number |  | Method of writing off analogs |
| `composition[].rowNumber` | number |  | Row number in the composition table |
| `composition[].notUsedInProduction` | boolean |  | Whether the material is not used in production |
| `composition[].analogs` | object[] |  | Analog nomenclatures for this composition line |
| `composition[].analogs[].nomenclature` | string (uuid) |  | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].analogs[].characteristic` | string (uuid) \| null |  | Characteristic UUID of the analog nomenclature |
| `composition[].analogs[].priority` | number |  | Analog priority / order |
| `composition[].analogs[].warehouseStock` | number |  | Available stock of the analog on warehouses |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) | A unique uuid key for the Specification |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/specification/api-create' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","nomenclature":"00000000-0000-0000-0000-000000000000","quantity":1,"currency":"00000000-0000-0000-0000-000000000000"}'
```

## api-update

`POST /org2/specification/api-update`

A request to update the specification

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `uuid` | string (uuid) | yes | A unique uuid key for the Specification |
| `specificationGroup` | string (uuid) |  | UUID of the specification group |
| `comment` | string |  | An optional text field for any additional notes or comments related to the document |
| `name` | string |  | Specification name |
| `nomenclature` | string (uuid) |  | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `quantity` | number |  | The amount of items |
| `currency` | string (uuid) |  | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `archived` | boolean |  | Whether the specification is archived |
| `specificationType` | number |  | Specification type code |
| `costCalculationMethod` | number |  | Cost calculation method code |
| `useAsTemplate` | boolean |  | Whether the specification is used as a template |
| `useOperationStages` | boolean |  | Whether production stages and operations are used |
| `version` | string |  | Specification version |
| `useSemiFinishedProducts` | boolean |  | Whether semi-finished products are used |
| `nomenclatureType` | number |  | Nomenclature type code |
| `operationsSum` | number |  | Total sum of production operations |
| `plannedCost` | number |  | Planned cost of the specification |
| `productionStages` | object[] |  | Production stages of the specification |
| `productionStages[].uniqueId` | string |  | Row unique id of the production stage |
| `productionStages[].stage` | object \| null |  | Production stage catalog reference |
| `productionStages[].priority` | number |  | Stage priority / order |
| `productionStages[].quantity` | number |  | The amount of items |
| `productionStages[].executionTime` | number |  | Stage execution time |
| `productionStages[].sum` | number |  | The sum of the document |
| `productionStages[].semiFinishedProduct` | object \| null |  | Semi-finished product linked to the stage |
| `productionStages[].semiFinishedCharacteristic` | object \| null |  | Characteristic of the semi-finished product |
| `productionOperations` | object[] |  | Production operations of the specification |
| `productionOperations[].uniqueId` | string |  | Row unique id of the production operation |
| `productionOperations[].relatesTo` | string |  | uniqueId of the related production stage |
| `productionOperations[].technologicalOperation` | object \| null |  | Technological operation catalog reference |
| `productionOperations[].performer` | object \| null |  | A unique identifier for the Employee, obtainable from the /employee/api-readList |
| `productionOperations[].contract` | object \| null |  | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `productionOperations[].executionTime` | number |  | Operation execution time |
| `productionOperations[].quantity` | number |  | The amount of items |
| `productionOperations[].price` | number |  | The price of the item/document |
| `productionOperations[].sum` | number |  | The sum of the document |
| `productionOperations[].catalogType` | object \| null |  | Catalog type of the technological operation |
| `operationDependencies` | object[] |  | Dependencies between production operations |
| `operationDependencies[].uniqueId` | string |  | uniqueId of the dependent production operation |
| `operationDependencies[].relatesTo` | string |  | uniqueId of the related preceding operation |
| `operationDependencies[].previousOperation` | string |  | Previous operation identifier |
| `composition` | object[] |  |  |
| `composition[].nomenclature` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].quantity` | number | yes | The amount of items |
| `composition[].price` | number | yes | The price of the item/document |
| `composition[].sum` | number |  | The sum of the document |
| `composition[].costShare` | number |  | Cost share |
| `composition[].netQuantity` | number |  | Net quantity |
| `composition[].loss` | number |  | Loss percent. Must match ((quantity - netQuantity) / quantity) * 100 when both loss and netQuantity are provided |
| `composition[].uniqueId` | string |  | Row unique id of the composition line |
| `composition[].relatesTo` | string |  | uniqueId of the related production stage |
| `composition[].nodeSpecification` | string (uuid) \| null |  |  |
| `composition[].analogWriteOffMethod` | number |  | Method of writing off analogs |
| `composition[].rowNumber` | number |  | Row number in the composition table |
| `composition[].notUsedInProduction` | boolean |  | Whether the material is not used in production |
| `composition[].analogs` | object[] |  | Analog nomenclatures for this composition line |
| `composition[].analogs[].nomenclature` | string (uuid) |  | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `composition[].analogs[].characteristic` | string (uuid) \| null |  | Characteristic UUID of the analog nomenclature |
| `composition[].analogs[].priority` | number |  | Analog priority / order |
| `composition[].analogs[].warehouseStock` | number |  | Available stock of the analog on warehouses |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) | A unique uuid key for the Specification |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/specification/api-update' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"00000000-0000-0000-0000-000000000000"}'
```

Interactive documentation with a test request option: [https://app.bimpsoft.com/docs](https://app.bimpsoft.com/docs). The OpenAPI specification is updated together with Bimp; this page is generated from it automatically.