# Sales of goods and services: Bimp API methods

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

Bimp API methods for the “Sales of goods and services” resource (`/org2/salesInvoice/…`): 11 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/salesInvoice/api-readList`](#api-read-list) | Read list of Sales invoice documents |
| [`POST /org2/salesInvoice/api-read`](#api-read) | Read single Sales invoice document |
| [`POST /org2/salesInvoice/api-create`](#api-create) | A request to create a new sales invoice document |
| [`POST /org2/salesInvoice/api-update`](#api-update) | A request to update the sales invoice document |
| [`POST /org2/salesInvoice/api-cancel`](#api-cancel) | Cancel a customer order document |
| [`POST /org2/salesInvoice/api-saveExternalId`](#api-save-external-id) | Creates or updates a mapping between a BIMP Sales Invoice and its unique identifier in an external system. Typically used after the invoice has been synced with platforms like Shopify, Prom, or Rozetka. |
| [`POST /org2/salesInvoice/api-readExternalId`](#api-read-external-id) | Retrieves the external identifier assigned to a specific BIMP Sales Invoice from a given source (e.g., "prom"). Useful for checking if a document has already been exported or linked to an external system. |
| [`POST /org2/salesInvoice/api-readByExternalId`](#api-read-by-external-id) | Finds and retrieves a BIMP Sales Invoice using its unique identifier from an external system. Returns key document details like number, date, and BIMP UUID, allowing you to sync or reference the internal document based on the external source. |
| [`POST /org2/salesInvoice/api-readExternalIdsList`](#api-read-external-ids-list) | Retrieves a paginated list of established mappings between BIMP Sales Invoices and their identifiers in external systems. Useful for auditing synchronized data or retrieving a batch of cross-references. |
| [`POST /org2/salesInvoice/api-readWithoutExternalId`](#api-read-without-external-id) | Retrieves a paginated list of BIMP Sales Invoices that have not yet been linked to the specified external source. Use this to identify documents that need to be synchronized or exported to platforms like Shopify, Prom, or Rozetka. |
| [`POST /org2/salesInvoice/api-deleteExternalId`](#api-delete-external-id) | Removes the mapping between a BIMP Sales Invoice and its external identifier. Useful for correcting synchronization errors, clearing stale data, or preparing a document for re-mapping to a different source system. |

## api-readList

`POST /org2/salesInvoice/api-readList`

Read list of Sales invoice documents

**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 |
| `periodable` | object[] |  | Period range as a tuple of two ISO 8601 date-time strings in UTC (e.g. '2012-10-05T14:48:00.000Z') |
| `organizations` | string (uuid)[] |  | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `managerialAccounting` | boolean |  | Show documents with managerial accounting |
| `bookkeperAccounting` | boolean |  | Show documents with bookkeper accounting |
| `orderUuid` | string (uuid) |  | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].uuid` | string (uuid) | A unique uuid key for the Sales invoice document |
| `[].name` | string |  |
| `[].date` | string |  |
| `[].sum` | number |  |
| `[].comment` | string |  |
| `[].TTN` | string |  |
| `[].EntryStatus` | number |  |
| `[].managerialAccounting` | boolean |  |
| `[].bookkeperAccounting` | boolean |  |
| `[].documentNumber` | string |  |
| `[].counterparty` | object |  |
| `[].counterparty.uuid` | string |  |
| `[].counterparty.name` | string |  |
| `[].status` | object |  |
| `[].status.uuid` | string |  |
| `[].status.name` | string |  |
| `[].organization` | object |  |
| `[].organization.uuid` | string |  |
| `[].organization.name` | string |  |
| `[].contract` | object |  |
| `[].contract.uuid` | string |  |
| `[].contract.name` | string |  |
| `[].currency` | object |  |
| `[].currency.uuid` | string |  |
| `[].currency.name` | string |  |
| `[].responsible` | object |  |
| `[].responsible.uuid` | string |  |
| `[].responsible.name` | string |  |
| `[].project` | object |  |
| `[].project.uuid` | string |  |
| `[].project.name` | string |  |

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

## api-read

`POST /org2/salesInvoice/api-read`

Read single Sales invoice document

**Request body (JSON)**

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

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) | A unique uuid key for the Sales invoice document |
| `name` | string |  |
| `date` | string |  |
| `sum` | number |  |
| `comment` | string |  |
| `TTN` | string |  |
| `documentNumber` | string |  |
| `counterparty` | object |  |
| `counterparty.uuid` | string |  |
| `counterparty.name` | string |  |
| `status` | object |  |
| `status.uuid` | string |  |
| `status.name` | string |  |
| `organization` | object |  |
| `organization.uuid` | string |  |
| `organization.name` | string |  |
| `responsible` | object |  |
| `responsible.uuid` | string |  |
| `responsible.name` | string |  |
| `project` | object |  |
| `project.uuid` | string |  |
| `project.name` | string |  |
| `VATaccounted` | boolean |  |
| `VAT` | number |  |
| `lineOfBusiness` | object |  |
| `lineOfBusiness.uuid` | string |  |
| `lineOfBusiness.name` | string |  |
| `priceList` | object |  |
| `priceList.uuid` | string |  |
| `priceList.name` | string |  |
| `warehouse` | object |  |
| `warehouse.uuid` | string |  |
| `warehouse.name` | string |  |
| `settlementType` | object |  |
| `settlementType.uuid` | string |  |
| `settlementType.name` | string |  |
| `invoiceForCustomerPayment` | object | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |
| `invoiceForCustomerPayment.uuid` | string (uuid) |  |
| `invoiceForCustomerPayment.name` | string |  |
| `contract` | object |  |
| `contract.uuid` | string |  |
| `contract.name` | string |  |
| `contract.currency` | object |  |
| `contract.currency.uuid` | string |  |
| `contract.currency.name` | string |  |
| `processing` | boolean | An informational flag marking the document as related to tolling (processing) |
| `accountingVATaccounted` | boolean | Is VAT taken into account in the accounting (BU) stock lines? |
| `editAccountingProducts` | boolean | When true, the accounting (BU) stock lines are edited separately from the main ones |
| `products` | object[] |  |
| `products[].cost` | number | Product cost |
| `products[].count` | number | Product count |
| `products[].reserve` | number | Product reserve |
| `products[].sum` | number |  |
| `products[].VAT` | number |  |
| `products[].VATamount` | object |  |
| `products[].VATamount.uuid` | string |  |
| `products[].VATamount.name` | string |  |
| `products[].unitOfMeasurement` | object |  |
| `products[].unitOfMeasurement.uuid` | string |  |
| `products[].unitOfMeasurement.name` | string |  |
| `products[].product` | object |  |
| `products[].product.uuid` | string |  |
| `products[].product.name` | string |  |
| `products[].parent` | object |  |
| `products[].parent.uuid` | string (uuid) | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `products[].parent.name` | string | Product parent name |
| `products[].party` | string (uuid) \| null | Party / batch UUID actually used in the line |
| `products[].serialNumbers` | string (uuid)[] | Serial number UUIDs actually used in the line |
| `accountingProducts` | object[] | Accounting (BU) stock lines with the same structure as products |
| `accountingProducts[].cost` | number | Product cost |
| `accountingProducts[].count` | number | Product count |
| `accountingProducts[].reserve` | number | Product reserve |
| `accountingProducts[].sum` | number |  |
| `accountingProducts[].VAT` | number |  |
| `accountingProducts[].VATamount` | object |  |
| `accountingProducts[].VATamount.uuid` | string |  |
| `accountingProducts[].VATamount.name` | string |  |
| `accountingProducts[].unitOfMeasurement` | object |  |
| `accountingProducts[].unitOfMeasurement.uuid` | string |  |
| `accountingProducts[].unitOfMeasurement.name` | string |  |

The full list of fields is in the [interactive documentation](https://app.bimpsoft.com/docs).

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

## api-create

`POST /org2/salesInvoice/api-create`

A request to create a new sales invoice document

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `counterparty` | object | yes |  |
| `counterparty.uuid` | string (uuid) | yes | A unique identifier for a counterparty of type 'isCustomer'.You can retrieve this UUID using the /counterparty/api-readList request |
| `contract` | object | yes |  |
| `contract.uuid` | string (uuid) | yes | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `VATaccounted` | boolean | yes | Value indicating whether VAT (Value Added Tax) has been accounted for |
| `TTN` | string |  | The number of the TTN |
| `comment` | string |  | An optional text field for any additional notes or comments related to the document |
| `date` | string |  | The document's date in the format 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-05-16T09:17:49') |
| `documentNumber` | string |  | The document's number. Use this field if you need to specify a custom number |
| `project` | object | yes |  |
| `project.uuid` | string (uuid) | yes | A unique identifier for the Project, obtainable from the /project/api-readList request |
| `lineOfBusiness` | object | yes |  |
| `lineOfBusiness.uuid` | string (uuid) | yes | A unique identifier for the Line of Business, obtainable from the /lineOfBusiness/api-readList request |
| `warehouse` | object | yes |  |
| `warehouse.uuid` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `responsible` | object |  |  |
| `responsible.uuid` | string (uuid) | yes | A unique identifier for the Employee, obtainable from the /employee/api-readList request |
| `priceList` | object |  |  |
| `priceList.uuid` | string (uuid) | yes | A unique identifier for the Price List, obtainable from the /priceList/api-readList request |
| `currency` | object | yes |  |
| `currency.uuid` | string (uuid) | yes | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `organization` | object |  |  |
| `organization.uuid` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `invoiceForCustomerPayment` | object |  |  |
| `invoiceForCustomerPayment.uuid` | string (uuid) | yes | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |
| `managerialAccounting` | boolean | yes | Управлінський облік |
| `bookkeperAccounting` | boolean | yes | Бухгалтерський облік |
| `processing` | boolean |  | An informational flag marking the document as related to tolling (processing) |
| `accountingVATaccounted` | boolean |  | Is VAT taken into account in the accounting (BU) stock lines? |
| `editAccountingProducts` | boolean |  | When true, the accounting (BU) stock lines are edited separately from the main ones |
| `products` | object[] |  |  |
| `products[].cost` | number | yes | Product cost |
| `products[].count` | number | yes | Product count |
| `products[].reserve` | number | yes | Product reserve |
| `products[].parent` | object |  |  |
| `products[].parent.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `products[].parent.name` | string | yes | Product parent name |
| `products[].party` | string (uuid) |  | Party / batch UUID from the party catalog (column «Номер партії») |
| `products[].serialNumbers` | string (uuid)[] |  | Serial number UUIDs from party.serialNumbers (column «Серія»). Pass together with party; the count must equal the line count. Exactly these serials are written off, without automatic replacement. |
| `products[].VATamount` | object |  |  |
| `products[].VATamount.uuid` | string (uuid) | yes | A unique identifier for the VAT, obtainable from the /vat/api-readList request |
| `products[].unitOfMeasurement` | object |  |  |
| `products[].unitOfMeasurement.uuid` | string (uuid) | yes | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `products[].product` | object | yes |  |
| `products[].product.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `accountingProducts` | object[] |  | Accounting (BU) stock lines with the same structure as products |
| `accountingProducts[].cost` | number | yes | Product cost |
| `accountingProducts[].count` | number | yes | Product count |
| `accountingProducts[].reserve` | number | yes | Product reserve |
| `accountingProducts[].parent` | object |  |  |
| `accountingProducts[].parent.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `accountingProducts[].parent.name` | string | yes | Product parent name |
| `accountingProducts[].party` | string (uuid) |  | Party / batch UUID from the party catalog (column «Номер партії») |
| `accountingProducts[].serialNumbers` | string (uuid)[] |  | Serial number UUIDs from party.serialNumbers (column «Серія»). Pass together with party; the count must equal the line count. Exactly these serials are written off, without automatic replacement. |
| `accountingProducts[].VATamount` | object |  |  |
| `accountingProducts[].VATamount.uuid` | string (uuid) | yes | A unique identifier for the VAT, obtainable from the /vat/api-readList request |
| `accountingProducts[].unitOfMeasurement` | object |  |  |
| `accountingProducts[].unitOfMeasurement.uuid` | string (uuid) | yes | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `accountingProducts[].product` | object | yes |  |
| `accountingProducts[].product.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `populateBatchesWhenSellingGoods` | boolean |  | If set to "true", batch lines are populated for items tracked by batch. Cannot be combined with explicit party / serialNumbers in products. Not sent when lines take party / serialNumbers from invoiceForCustomerPayment (lines without them copy the ones assigned in the matching order line). |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-create' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"counterparty":{"uuid":"00000000-0000-0000-0000-000000000000"},"contract":{"uuid":"00000000-0000-0000-0000-000000000000"},"VATaccounted":true,"project":{"uuid":"00000000-0000-0000-0000-000000000000"},"lineOfBusiness":{"uuid":"00000000-0000-0000-0000-000000000000"},"warehouse":{"uuid":"00000000-0000-0000-0000-000000000000"},"currency":{"uuid":"00000000-0000-0000-0000-000000000000"},"managerialAccounting":true,"bookkeperAccounting":false}'
```

## api-update

`POST /org2/salesInvoice/api-update`

A request to update the sales invoice document

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `uuid` | string (uuid) | yes | A unique uuid key for the Sales invoice document |
| `contract` | object |  |  |
| `contract.uuid` | string (uuid) | yes | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `VATaccounted` | boolean |  | Value indicating whether VAT (Value Added Tax) has been accounted for |
| `TTN` | string |  | The number of the TTN |
| `comment` | string |  | An optional text field for any additional notes or comments related to the document |
| `date` | string |  | The document's date in the format 'YYYY-MM-DDTHH:MM:SS' (e.g., '2025-05-16T09:17:49') |
| `documentNumber` | string |  | The document's number. Use this field if you need to specify a custom number |
| `project` | object |  |  |
| `project.uuid` | string (uuid) | yes | A unique identifier for the Project, obtainable from the /project/api-readList request |
| `lineOfBusiness` | object |  |  |
| `lineOfBusiness.uuid` | string (uuid) | yes | A unique identifier for the Line of Business, obtainable from the /lineOfBusiness/api-readList request |
| `warehouse` | object |  |  |
| `warehouse.uuid` | string (uuid) | yes | A unique identifier for the Warehouse, obtainable from the /warehouse/api-readList request |
| `responsible` | object |  |  |
| `responsible.uuid` | string (uuid) | yes | A unique identifier for the Employee, obtainable from the /employee/api-readList request |
| `priceList` | object |  |  |
| `priceList.uuid` | string (uuid) | yes | A unique identifier for the Price List, obtainable from the /priceList/api-readList request |
| `currency` | object |  |  |
| `currency.uuid` | string (uuid) | yes | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `organization` | object |  |  |
| `organization.uuid` | string (uuid) | yes | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `invoiceForCustomerPayment` | object |  |  |
| `invoiceForCustomerPayment.uuid` | string (uuid) | yes | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |
| `processing` | boolean |  | An informational flag marking the document as related to tolling (processing) |
| `accountingVATaccounted` | boolean |  | Is VAT taken into account in the accounting (BU) stock lines? |
| `editAccountingProducts` | boolean |  | When true, the accounting (BU) stock lines are edited separately from the main ones |
| `populateBatchesWhenSellingGoods` | boolean |  | If set to "true", batch lines are populated for items tracked by batch. Cannot be combined with explicit party / serialNumbers in products. Not sent when lines take party / serialNumbers from invoiceForCustomerPayment (lines without them copy the ones assigned in the matching order line). |
| `products` | object[] |  |  |
| `products[].cost` | number | yes | Product cost |
| `products[].count` | number | yes | Product count |
| `products[].reserve` | number | yes | Product reserve |
| `products[].parent` | object |  |  |
| `products[].parent.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `products[].parent.name` | string | yes | Product parent name |
| `products[].party` | string (uuid) |  | Party / batch UUID from the party catalog (column «Номер партії») |
| `products[].serialNumbers` | string (uuid)[] |  | Serial number UUIDs from party.serialNumbers (column «Серія»). Pass together with party; the count must equal the line count. Exactly these serials are written off, without automatic replacement. |
| `products[].VATamount` | object |  |  |
| `products[].VATamount.uuid` | string (uuid) | yes | A unique identifier for the VAT, obtainable from the /vat/api-readList request |
| `products[].unitOfMeasurement` | object |  |  |
| `products[].unitOfMeasurement.uuid` | string (uuid) | yes | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `products[].product` | object | yes |  |
| `products[].product.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `accountingProducts` | object[] |  | Accounting (BU) stock lines with the same structure as products |
| `accountingProducts[].cost` | number | yes | Product cost |
| `accountingProducts[].count` | number | yes | Product count |
| `accountingProducts[].reserve` | number | yes | Product reserve |
| `accountingProducts[].parent` | object |  |  |
| `accountingProducts[].parent.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |
| `accountingProducts[].parent.name` | string | yes | Product parent name |
| `accountingProducts[].party` | string (uuid) |  | Party / batch UUID from the party catalog (column «Номер партії») |
| `accountingProducts[].serialNumbers` | string (uuid)[] |  | Serial number UUIDs from party.serialNumbers (column «Серія»). Pass together with party; the count must equal the line count. Exactly these serials are written off, without automatic replacement. |
| `accountingProducts[].VATamount` | object |  |  |
| `accountingProducts[].VATamount.uuid` | string (uuid) | yes | A unique identifier for the VAT, obtainable from the /vat/api-readList request |
| `accountingProducts[].unitOfMeasurement` | object |  |  |
| `accountingProducts[].unitOfMeasurement.uuid` | string (uuid) | yes | A unique identifier for the Unit of Measurement, obtainable from the /unitsOfMeasurment/api-readList request |
| `accountingProducts[].product` | object | yes |  |
| `accountingProducts[].product.uuid` | string (uuid) | yes | A unique identifier for the Nomenclature, obtainable from the /nomenclature/api-readList request |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `uuid` | string (uuid) |  |

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

## api-cancel

`POST /org2/salesInvoice/api-cancel`

Cancel a customer order document

**Request body (JSON)**

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

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `success` | boolean (true) |  |

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

## api-saveExternalId

`POST /org2/salesInvoice/api-saveExternalId`

Creates or updates a mapping between a BIMP Sales Invoice and its unique identifier in an external system. Typically used after the invoice has been synced with platforms like Shopify, Prom, or Rozetka.

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `salesInvoiceUuid` | string (uuid) | yes | The unique internal identifier (GUID) of the Sales Invoice in BIMP. |
| `source` | string | yes | Identifier of the external system (e.g., "prom", "shopify"). The value is case-insensitive and automatically normalized (trimmed and lowercased). |
| `externalId` | string | yes | The unique identifier assigned to this Sales Invoice by the external system. |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Indicates whether the mapping between the BIMP Sales Invoice (document of goods delivery) and the external system identifier was successfully established. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-saveExternalId' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"salesInvoiceUuid":"00000000-0000-0000-0000-000000000000","source":"string","externalId":"string"}'
```

## api-readExternalId

`POST /org2/salesInvoice/api-readExternalId`

Retrieves the external identifier assigned to a specific BIMP Sales Invoice from a given source (e.g., "prom"). Useful for checking if a document has already been exported or linked to an external system.

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `salesInvoiceUuid` | string (uuid) | yes | The unique identifier of the sales document, which can be obtained from the /salesInvoice/api-readList query |
| `source` | string | yes | Identifier of the external system (e.g., "prom", "shopify") to lookup the mapping. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-readExternalId' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"salesInvoiceUuid":"00000000-0000-0000-0000-000000000000","source":"string"}'
```

## api-readByExternalId

`POST /org2/salesInvoice/api-readByExternalId`

Finds and retrieves a BIMP Sales Invoice using its unique identifier from an external system. Returns key document details like number, date, and BIMP UUID, allowing you to sync or reference the internal document based on the external source.

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `source` | string | yes | Identifier of the external source system (e.g., "prom", "shopify"). |
| `externalId` | string | yes | The unique identifier assigned to the Sales Invoice by the external system. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-readByExternalId' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"source":"string","externalId":"string"}'
```

## api-readExternalIdsList

`POST /org2/salesInvoice/api-readExternalIdsList`

Retrieves a paginated list of established mappings between BIMP Sales Invoices and their identifiers in external systems. Useful for auditing synchronized data or retrieving a batch of cross-references.

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].salesInvoiceUuid` | string (uuid) | Unique internal identifier (GUID) of the Sales Invoice in the BIMP system. |
| `[].date` | string | Sales Invoice creation date and time in ISO 8601 format. |
| `[].number` | string | Internal human-readable Sales Invoice number (e.g., "SI-00001"). |
| `[].source` | string | Identifier of the external source system (e.g., "prom", "shopify", "rozetka"). |
| `[].externalId` | string | The unique identifier assigned to this Sales Invoice by the external system. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-readExternalIdsList' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## api-readWithoutExternalId

`POST /org2/salesInvoice/api-readWithoutExternalId`

Retrieves a paginated list of BIMP Sales Invoices that have not yet been linked to the specified external source. Use this to identify documents that need to be synchronized or exported to platforms like Shopify, Prom, or Rozetka.

**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 |
| `source` | string | yes | Identifier of the external source system (e.g., "prom", "shopify"). The system will filter out Sales Invoices already linked to this specific source. |

**Response: `data` field**

| Field | Type | Description |
|---|---|---|
| `[].salesInvoiceUuid` | string (uuid) | Unique internal identifier (GUID) of the Sales Invoice in the BIMP system. |
| `[].number` | string | Internal human-readable Sales Invoice number (e.g., "SI-00001"). |
| `[].date` | string | Sales Invoice creation date and time in ISO 8601 format. |
| `[].amount` | number | Total amount of the Sales Invoice. |
| `[].comment` | string | Optional internal comment or customer notes attached to the Sales Invoice. |
| `[].counterpartyName` | string | The name of the customer (counterparty) associated with the Sales Invoice. |
| `[].counterpartyUuid` | string (uuid) | Unique internal identifier (GUID) of the customer in the BIMP system. |
| `[].currency` | string | Document currency code (e.g., "UAH", "USD"). |

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

## api-deleteExternalId

`POST /org2/salesInvoice/api-deleteExternalId`

Removes the mapping between a BIMP Sales Invoice and its external identifier. Useful for correcting synchronization errors, clearing stale data, or preparing a document for re-mapping to a different source system.

**Request body (JSON)**

| Field | Type | Required | Description |
|---|---|---|---|
| `salesInvoiceUuid` | string (uuid) | yes | The unique identifier of the sales document, which can be obtained from the /salesInvoice/api-readList query |
| `source` | string |  | Identifier of the external system (e.g., "prom", "shopify") to remove the mapping for. If omitted, all external mappings for this Sales Invoice may be affected depending on logic. |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/salesInvoice/api-deleteExternalId' \
  -H 'access-token: <company token>' \
  -H 'Content-Type: application/json' \
  -d '{"salesInvoiceUuid":"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.