# Замовлення покупця: методи API Bimp

URL: https://bimpsoft.com/help/developers/api-reference/invoice-for-customer-payment/

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

| Метод | Що робить |
|---|---|
| [`POST /org2/invoiceForCustomerPayment/api-insert`](#api-insert) |  |
| [`POST /org2/invoiceForCustomerPayment/api-readStatuses`](#api-read-statuses) | A request to retrieve the available statuses for a customer order document |
| [`POST /org2/invoiceForCustomerPayment/api-updateStatus`](#api-update-status) | A request to update the status of a customer order document |
| [`POST /org2/invoiceForCustomerPayment/api-saveExternalId`](#api-save-external-id) | Creates or updates a mapping between a BIMP order and its unique identifier in an external system. Typically called after an order has been successfully created or matched in the external source. |
| [`POST /org2/invoiceForCustomerPayment/api-readExternalId`](#api-read-external-id) | Retrieves detailed information about a single BIMP invoice using its corresponding identifier from an external system. Used for verifying the status and details of a specific synced order. |
| [`POST /org2/invoiceForCustomerPayment/api-readByExternalId`](#api-read-by-external-id) | Retrieves detailed information about an order using its identifier from an external system. Used to sync the current status, amount, and comments of an order within BIMP. |
| [`POST /org2/invoiceForCustomerPayment/api-readExternalIdsList`](#api-read-external-ids-list) | Retrieves a list of existing mappings between BIMP invoices and external system identifiers. Used to review already synchronized orders. |
| [`POST /org2/invoiceForCustomerPayment/api-readWithoutExternalId`](#api-read-without-external-id) | Retrieves a list of customer invoices (orders) that do not have a mapping for the specified external source. Primarily used to identify new orders that need to be synchronized with an external system. |
| [`POST /org2/invoiceForCustomerPayment/api-deleteExternalId`](#api-delete-external-id) | Removes the link between a BIMP order and its external identifier. Used to correct synchronization errors or re-map an order to a different source. |
| [`POST /org2/invoiceForCustomerPayment/api-readList`](#api-read-list) | A request to view a list of customer orders |
| [`POST /org2/invoiceForCustomerPayment/api-read`](#api-read) | A request to obtain detailed information for a particular customer order |
| [`POST /org2/invoiceForCustomerPayment/api-create`](#api-create) | A request to create a new customer order |
| [`POST /org2/invoiceForCustomerPayment/api-update`](#api-update) | A request to update or add information to an existing customer order |
| [`POST /org2/invoiceForCustomerPayment/api-cancel`](#api-cancel) | Cancel a customer order document |

## api-insert

`POST /org2/invoiceForCustomerPayment/api-insert`

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `dateTime` | string (iso-date-time) |  |  |
| `shipmentDateTime` | string (date-time) |  | Дата відвантаження |
| `projectUuid` | string (uuid) | так |  |
| `managerUuid` | string (uuid) | так |  |
| `contractUuid` | string (uuid) | так |  |
| `lineOfBusinessUuid` | string (uuid) | так | Вид діяльності |
| `organizationUuid` | string (uuid) | так |  |
| `warehouseUuid` | string (uuid) | так |  |
| `customerUuid` | string (uuid) | так |  |
| `statusUuid` | string (uuid) | так |  |
| `priceListUuid` | string (uuid) |  |  |
| `bankAccount` | string (uuid) |  | Банківський рахунок |
| `mutualSettlementsType` | string (uuid) |  | Вид взаєморозрахунків |
| `addVAT` | boolean | так | Додати НДС |
| `setUpByContract` | boolean | так | Чи створений на основі договору |
| `stocks` | object[] | так |  |
| `stocks[].nomenclatureUuid` | string (uuid) | так |  |
| `stocks[].percentageDiscount` | number | так | Процент знижки |
| `stocks[].reserve` | number | так | Зарезервована кількість |
| `stocks[].count` | number | так | Кількість в одиницях виміру номенклатури |
| `stocks[].cost` | number | так | Вартість за одну одиницю без знижки |
| `stocks[].warehouseUuid` | string (uuid) |  |  |
| `comment` | string |  |  |
| `documentNumber` | string |  | Номер документу |

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

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

```bash
curl -X POST 'https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-insert' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"projectUuid":"00000000-0000-0000-0000-000000000000","managerUuid":"00000000-0000-0000-0000-000000000000","contractUuid":"00000000-0000-0000-0000-000000000000","lineOfBusinessUuid":"00000000-0000-0000-0000-000000000000","organizationUuid":"00000000-0000-0000-0000-000000000000","warehouseUuid":"00000000-0000-0000-0000-000000000000","customerUuid":"00000000-0000-0000-0000-000000000000","statusUuid":"00000000-0000-0000-0000-000000000000","addVAT":true,"setUpByContract":false,"stocks":[{}]}'
```

## api-readStatuses

`POST /org2/invoiceForCustomerPayment/api-readStatuses`

A request to retrieve the available statuses for a customer order document

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

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) |  |
| `[].name` | string |  |
| `[].color` | string |  |

```bash
curl -X POST 'https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readStatuses' \
  -H 'access-token: <токен компанії>'
```

## api-updateStatus

`POST /org2/invoiceForCustomerPayment/api-updateStatus`

A request to update the status of a customer order document

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `invoiceUuid` | string (uuid) | так | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |
| `statusUuid` | string (uuid) | так |  |

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

## api-saveExternalId

`POST /org2/invoiceForCustomerPayment/api-saveExternalId`

Creates or updates a mapping between a BIMP order and its unique identifier in an external system. Typically called after an order has been successfully created or matched in the external source.

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `orderUuid` | string (uuid) | так | The unique internal identifier (GUID) of the order in BIMP. |
| `source` | string | так | Identifier of the external system (e.g., "prom", "shopify"). The value is case-insensitive and automatically normalized. |
| `externalId` | string | так | The unique order identifier assigned by the external system. |

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

| Поле | Тип | Опис |
|---|---|---|
| `success` | boolean | Indicates whether the mapping between the BIMP Customer Order and the external system identifier was successfully saved. |

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

## api-readExternalId

`POST /org2/invoiceForCustomerPayment/api-readExternalId`

Retrieves detailed information about a single BIMP invoice using its corresponding identifier from an external system. Used for verifying the status and details of a specific synced order.

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `orderUuid` | string (uuid) | так | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/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/invoiceForCustomerPayment/api-readExternalId' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"orderUuid":"00000000-0000-0000-0000-000000000000","source":"string"}'
```

## api-readByExternalId

`POST /org2/invoiceForCustomerPayment/api-readByExternalId`

Retrieves detailed information about an order using its identifier from an external system. Used to sync the current status, amount, and comments of an order within BIMP.

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `source` | string | так | Identifier of the external source system (e.g., "prom", "shopify"). |
| `externalId` | string | так | The unique order identifier assigned by the external system. |

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

## api-readExternalIdsList

`POST /org2/invoiceForCustomerPayment/api-readExternalIdsList`

Retrieves a list of existing mappings between BIMP invoices and external system identifiers. Used to review already synchronized orders.

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `source` | string |  | Filter mappings by a specific external system (e.g. "prom"). |
| `orderUuid` | string (uuid) |  | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |

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

| Поле | Тип | Опис |
|---|---|---|
| `[].orderUuid` | string (uuid) | Unique internal identifier (GUID) of the order in the BIMP system. |
| `[].date` | string | Order creation date and time in ISO 8601 format. |
| `[].number` | string | Internal human-readable order number (e.g., "SO-00001"). |
| `[].source` | string | Identifier of the external source system (e.g., "prom", "shopify", "rozetka"). |
| `[].externalId` | string | The unique identifier assigned to this order by the external system. |

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

## api-readWithoutExternalId

`POST /org2/invoiceForCustomerPayment/api-readWithoutExternalId`

Retrieves a list of customer invoices (orders) that do not have a mapping for the specified external source. Primarily used to identify new orders that need to be synchronized with an external 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`**

| Поле | Тип | Опис |
|---|---|---|
| `[].orderUuid` | string (uuid) | Unique internal identifier (GUID) of the order in the BIMP system. |
| `[].number` | string | Internal human-readable order number (e.g., "SO-00001"). |
| `[].date` | string | Order creation date and time in ISO 8601 format. |
| `[].amount` | number | Total amount of the order. |
| `[].comment` | string | Optional internal comment or customer notes. |
| `[].counterpartyName` | string | The name of the customer (counterparty). |
| `[].counterpartyUuid` | string (uuid) | Unique internal identifier (GUID) of the customer in the BIMP system. |
| `[].currency` | string | Document currency code (e.g., "UAH", "USD"). |
| `[].statusName` | string | Current display name of the order status (e.g., "Pending", "Processing"). |

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

## api-deleteExternalId

`POST /org2/invoiceForCustomerPayment/api-deleteExternalId`

Removes the link between a BIMP order and its external identifier. Used to correct synchronization errors or re-map an order to a different source.

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `orderUuid` | string (uuid) | так | A unique identifier for the Invoice for customer payment, obtainable from the /invoiceForCustomerPayment/api-readList request |
| `source` | string |  | Identifier of the external system (e.g. "prom") to remove mapping for. |

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

## api-readList

`POST /org2/invoiceForCustomerPayment/api-readList`

A request to view a list of customer orders

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | Limit of paginated elemets |
| `status` | string (uuid) |  |  |
| `periodable` | object[] |  | Period range as a tuple of two ISO 8601 date-time strings in UTC (e.g. '2012-10-05T14:48:00.000Z') |
| `changeStatusTime` | 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 |
| `number` | string |  | Filter by document number |

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

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) | A unique uuid key for an Invoice for customer payment document |
| `[].docNumber` | string | The document's number. Use this field if you need to specify a custom number |
| `[].name` | string |  |
| `[].status` | string (uuid) |  |
| `[].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') |
| `[].buyer` | string (uuid) | A unique identifier for a counterparty of type 'isCustomer'.You can retrieve this UUID using the /counterparty/api-readList request |
| `[].sumOrdered` | number | Total amount of document (ordered goods) |
| `[].currency` | string (uuid) | A unique uuid key for a currency |
| `[].contract` | string (uuid) | The unique identifier for the counterparty's contract, specified in the buyer key. You can retrieve this UUID using the /contract/api-readList request |
| `[].TTN` | string | The number of the TTN |
| `[].quantityShipped` | number |  |
| `[].quantityOrdered` | number |  |
| `[].sumShipped` | number | Total amount of document (shipped goods) |
| `[].sumPayed` | number | Total payed amount |
| `[].organization` | string (uuid) | A unique identifier for the Organization, obtainable from the /organization/api-readList request |
| `[].products` | string (uuid)[] |  |
| `[].EntryStatus` | number |  |

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

## api-read

`POST /org2/invoiceForCustomerPayment/api-read`

A request to obtain detailed information for a particular customer order

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `uuid` | string (uuid) | так | A unique uuid key for an Invoice for customer payment document |

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

| Поле | Тип | Опис |
|---|---|---|
| `uuid` | string (uuid) |  |
| `comment` | string |  |
| `buyer` | string (uuid) |  |
| `date` | string (date-time) |  |
| `name` | string |  |
| `organization` | string (uuid) |  |
| `quantityOrdered` | number |  |
| `quantityShipped` | number |  |
| `status` | string (uuid) |  |
| `sumOrdered` | number | Total amount of the order |
| `sumPayed` | number |  |
| `sumShipped` | number |  |
| `TTN` | string |  |
| `docNumber` | string |  |
| `contract` | string (uuid) |  |
| `lineOfBusiness` | string (uuid) |  |
| `warehouse` | string (uuid) |  |
| `VATaccounted` | boolean |  |
| `VATamount` | number |  |
| `processing` | boolean | An informational flag marking the document as related to tolling (processing) |
| `products` | object[] |  |
| `products[].nomenclatureUuid` | string (uuid) |  |
| `products[].count` | number |  |
| `products[].VATamount` | number |  |
| `products[].cost` | number |  |
| `products[].amount` | number |  |
| `products[].discount` | number |  |
| `products[].discountPercentage` | number |  |
| `products[].shiped` | number |  |
| `products[].reserve` | number |  |
| `products[].modification` | string (uuid) \| null |  |
| `products[].party` | string (uuid) \| null |  |
| `products[].serialNumbers` | string (uuid)[] | Serial number UUIDs from party.serialNumbers (column «Серія») |
| `products[].machinery` | object |  |
| `products[].machinery.uuid` | string |  |
| `products[].machinery.name` | string |  |
| `products[].comment` | string |  |
| `products[].content` | string |  |
| `products[].users` | number |  |
| `products[].months` | number |  |
| `accountingProducts` | object[] |  |
| `accountingProducts[].nomenclatureUuid` | string (uuid) |  |
| `accountingProducts[].count` | number |  |
| `accountingProducts[].VATamount` | number |  |
| `accountingProducts[].cost` | number |  |
| `accountingProducts[].amount` | number |  |
| `accountingProducts[].discount` | number |  |
| `accountingProducts[].discountPercentage` | number |  |
| `accountingProducts[].shiped` | number |  |
| `accountingProducts[].reserve` | number |  |
| `accountingProducts[].modification` | string (uuid) \| null |  |
| `accountingProducts[].party` | string (uuid) \| null |  |
| `accountingProducts[].serialNumbers` | string (uuid)[] | Serial number UUIDs from party.serialNumbers (column «Серія») |
| `accountingProducts[].machinery` | object |  |
| `accountingProducts[].machinery.uuid` | string |  |
| `accountingProducts[].machinery.name` | string |  |
| `accountingProducts[].comment` | string |  |
| `accountingProducts[].content` | string |  |
| `accountingProducts[].users` | number |  |
| `accountingProducts[].months` | number |  |

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

## api-create

`POST /org2/invoiceForCustomerPayment/api-create`

A request to create a new customer order

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

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

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

## api-update

`POST /org2/invoiceForCustomerPayment/api-update`

A request to update or add information to an existing customer order

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

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

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

## api-cancel

`POST /org2/invoiceForCustomerPayment/api-cancel`

Cancel a customer order document

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `uuid` | string (uuid) | так | A unique uuid key for an Invoice for customer payment document |

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

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

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

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