# Контрагенти: методи API Bimp

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

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

| Метод | Що робить |
|---|---|
| [`POST /org2/counterparty/api-insert`](#api-insert) | A request to create a new counterparty |
| [`POST /org2/counterparty/api-update`](#api-update) | A request to update an existing counterparty |
| [`POST /org2/counterparty/api-updateAddresses`](#api-update-addresses) | A request to update the counterparty's addresses |
| [`POST /org2/counterparty/api-readStatuses`](#api-read-statuses) | A request to read the counterparty's addresses |
| [`POST /org2/counterparty/api-readList`](#api-read-list) | A request to view a list of company's counterparties |
| [`POST /org2/counterparty/api-updateStatus`](#api-update-status) | A request to update the counterparty's status |
| [`POST /org2/counterparty/api-read`](#api-read) | A request to obtain detailed information for a particular counterparty |
| [`POST /org2/counterparty/api-readAdditionalCharacteristics`](#api-read-additional-characteristics) | A request to obtain additional characteristics of counterparties |
| [`POST /org2/counterparty/api-saveExternalId`](#api-save-external-id) | Creates or updates the mapping between a counterparty and an external system ID (e.g., website user ID). |
| [`POST /org2/counterparty/api-readExternalId`](#api-read-external-id) | Retrieves the external system ID for a specific counterparty given the source system name. |
| [`POST /org2/counterparty/api-readByExternalId`](#api-read-by-external-id) | Identifies a counterparty by their external system ID. Returns null if no mapping exists. |
| [`POST /org2/counterparty/api-readExternalIdsList`](#api-read-external-ids-list) | Retrieves a paginated list of existing mappings with optional filtering by source or counterparty. |
| [`POST /org2/counterparty/api-readWithoutExternalId`](#api-read-without-external-id) | Retrieves a list of counterparties that do not have a mapping for the specified source system. |
| [`POST /org2/counterparty/api-deleteExternalId`](#api-delete-external-id) | Removes the mapping for a specific counterparty. If source is omitted, deletes all external mappings for this counterparty. |

## api-insert

`POST /org2/counterparty/api-insert`

A request to create a new counterparty

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `name` | string | так | Counterparty name |
| `managerUuid` | string (uuid) |  | A unique identifier for the Manager, obtainable from the /user/api-readList request |
| `AdditionalIdentifier` | string |  | Additional field about counterparty |
| `statusUuid` | string (uuid) |  | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request |
| `isCustomer` | boolean | так | Is he a customer? By default it is set to true |
| `isSupplier` | boolean | так | Is he a supplier? |
| `isSoleProprietor` | boolean | так | Is he a sole proprietor? |
| `email` | string (email) |  | Counterparty email |
| `phoneNumber` | string |  | Counterparty phone number |
| `vat` | string |  | The total amount of Value Added Tax (VAT) applied |
| `printFormName` | string |  | The name of the counterparty that will be displayed in printed documents. If the field is not filled in, the name field is duplicated |
| `edrpou` | string |  | Counterparty edrpou |
| `sourceOfAttractionUuid` | string (uuid) |  |  |
| `contacts` | object[] |  |  |
| `contacts[].post` | string | так | Counterparty post |
| `contacts[].name` | string | так | Counterparty name |
| `contacts[].isMain` | boolean | так | Is it the main contact? |
| `contacts[].phoneNumber` | string | так | Counterparty phone number |
| `bankAccounts` | object[] |  |  |
| `bankAccounts[].iban` | string | так | Bank account iban |
| `bankAccounts[].isMain` | boolean | так | Is it the main bank account? |
| `bankAccounts[].currencyUuid` | string (uuid) | так | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `bankAccounts[].bankAccountTypeUuid` | string (uuid) | так | A unique identifier for the Bank account type, obtainable from the /bankAccounts/api-readTypes request |
| `addresses` | object[] |  |  |
| `addresses[].value` | string | так | Address name |
| `addresses[].addressTypeUuid` | string (uuid) | так | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |
| `additionalCharacteristics` | object[] |  |  |
| `additionalCharacteristics[].vaule` | string | так | Additional characteristic name |
| `additionalCharacteristics[].additionalCharacteristicTypeUuid` | string (uuid) | так | Additional characteristic type |
| `createContract` | boolean |  | Need to automatically create a contract? |
| `integration` | object |  | The object is filled if created from integration system |
| `integration.system` | string (uuid) | так | The integration system through which the element was created |
| `integration.externalId` | string | так | Unique element code from the integration system |

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

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

```bash
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-insert' \
  -H 'access-token: <токен компанії>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","isCustomer":true,"isSupplier":false,"isSoleProprietor":false}'
```

## api-update

`POST /org2/counterparty/api-update`

A request to update an existing counterparty

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `uuid` | string (uuid) | так | A unique uuid key of the counterparty to update |
| `name` | string |  | Counterparty name |
| `managerUuid` | string (uuid) |  | A unique identifier for the Manager, obtainable from the /user/api-readList request |
| `AdditionalIdentifier` | string |  | Additional field about counterparty |
| `statusUuid` | string (uuid) |  | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request |
| `isCustomer` | boolean |  | Is he a customer? |
| `isSupplier` | boolean |  | Is he a supplier? |
| `isSoleProprietor` | boolean |  | Is he a sole proprietor? |
| `email` | string (email) |  | Counterparty email |
| `phoneNumber` | string |  | Counterparty phone number |
| `vat` | string |  | The total amount of Value Added Tax (VAT) applied |
| `printFormName` | string |  | The name of the counterparty that will be displayed in printed documents. |
| `edrpou` | string |  | Counterparty edrpou |
| `sourceOfAttractionUuid` | string (uuid) |  |  |
| `contacts` | object[] |  |  |
| `contacts[].post` | string | так | Counterparty post |
| `contacts[].name` | string | так | Counterparty name |
| `contacts[].isMain` | boolean | так | Is it the main contact? |
| `contacts[].phoneNumber` | string | так | Counterparty phone number |
| `bankAccounts` | object[] |  |  |
| `bankAccounts[].iban` | string | так | Bank account iban |
| `bankAccounts[].isMain` | boolean | так | Is it the main bank account? |
| `bankAccounts[].currencyUuid` | string (uuid) | так | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
| `bankAccounts[].bankAccountTypeUuid` | string (uuid) | так | A unique identifier for the Bank account type, obtainable from the /bankAccounts/api-readTypes request |
| `addresses` | object[] |  |  |
| `addresses[].value` | string | так | Address name |
| `addresses[].addressTypeUuid` | string (uuid) | так | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |
| `additionalCharacteristics` | object[] |  |  |
| `additionalCharacteristics[].vaule` | string | так | Additional characteristic name |
| `additionalCharacteristics[].additionalCharacteristicTypeUuid` | string (uuid) | так | Additional characteristic type |
| `createContract` | boolean |  | Need to automatically create a contract? |
| `integration` | object |  | The object is filled if created from integration system |
| `integration.system` | string (uuid) | так | The integration system through which the element was created |
| `integration.externalId` | string | так | Unique element code from the integration system |

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

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

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

## api-updateAddresses

`POST /org2/counterparty/api-updateAddresses`

A request to update the counterparty's addresses

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `counterpartyUuid` | string (uuid) | так | A unique identifier for a counterparty of type 'isCustomer'.You can retrieve this UUID using the /counterparty/api-readList request |
| `addresses` | object[] | так |  |
| `addresses[].value` | string | так | Address name |
| `addresses[].addressTypeUuid` | string (uuid) | так | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |

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

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

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

## api-readStatuses

`POST /org2/counterparty/api-readStatuses`

A request to read the counterparty's addresses

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

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

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

## api-readList

`POST /org2/counterparty/api-readList`

A request to view a list of company's counterparties

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `pagination` | object | так |  |
| `pagination.offset` | number | так | Begin from {offset} elements |
| `pagination.count` | number | так | 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') |
| `edrpou` | string |  | Filter by edrpou |
| `email` | string |  | Filter by email |
| `phoneNumber` | string |  | Filter by phone number |
| `individualTaxNumber` | string |  | Filter by individual tax number |
| `name` | string |  | Filter by name |
| `types` | string ("isCustomer", "isSupplier", "isSoleProprietor")[] |  |  |
| `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 |

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

| Поле | Тип | Опис |
|---|---|---|
| `[].uuid` | string (uuid) |  |
| `[].name` | string |  |
| `[].edrpou` | string |  |
| `[].individualTaxNumber` | string |  |
| `[].email` | string |  |
| `[].phoneNumber` | string |  |
| `[].isCustomer` | boolean | Чи покупець |
| `[].isSupplier` | boolean | Чи постачальник |
| `[].isSoleProprietor` | boolean | Чи ФОП |
| `[].code` | string |  |
| `[].printName` | string |  |
| `[].addresses` | object[] |  |
| `[].addresses[].value` | string |  |
| `[].addresses[].isMain` | boolean |  |
| `[].addresses[].type` | object |  |
| `[].addresses[].type.name` | string |  |
| `[].addresses[].type.GUID` | string (uuid) |  |
| `[].addresses[].type.type` | number |  |

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

## api-updateStatus

`POST /org2/counterparty/api-updateStatus`

A request to update the counterparty's status

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `counterpartyUuid` | string (uuid) | так | A unique identifier for a counterparty of type 'isCustomer'.You can retrieve this UUID using the /counterparty/api-readList request |
| `statusUuid` | string (uuid) | так | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request |

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

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

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

## api-read

`POST /org2/counterparty/api-read`

A request to obtain detailed information for a particular counterparty

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

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

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

| Поле | Тип | Опис |
|---|---|---|
| `uuid` | string (uuid) |  |
| `name` | string |  |
| `edrpou` | string |  |
| `individualTaxNumber` | string |  |
| `email` | string |  |
| `phoneNumber` | string |  |
| `isCustomer` | boolean | Чи покупець |
| `isSupplier` | boolean | Чи постачальник |
| `isSoleProprietor` | boolean | Чи ФОП |
| `code` | string |  |
| `printName` | string |  |
| `addresses` | object[] |  |
| `addresses[].value` | string |  |
| `addresses[].isMain` | boolean |  |
| `addresses[].type` | object |  |
| `addresses[].type.name` | string |  |
| `addresses[].type.GUID` | string (uuid) |  |
| `addresses[].type.type` | number |  |

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

## api-readAdditionalCharacteristics

`POST /org2/counterparty/api-readAdditionalCharacteristics`

A request to obtain additional characteristics of counterparties

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

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

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

## api-saveExternalId

`POST /org2/counterparty/api-saveExternalId`

Creates or updates the mapping between a counterparty and an external system ID (e.g., website user ID).

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

| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
| `counterpartyUuid` | string (uuid) | так | A unique identifier for the Counterparty, obtainable from the /counterparty/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 counterparty in the external system (e.g., user ID on the website, database key, login). |

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

| Поле | Тип | Опис |
|---|---|---|
| `success` | boolean | Indicates whether the mapping between the BIMP Counterparty and the external system ID was successfully established. |

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

## api-readExternalId

`POST /org2/counterparty/api-readExternalId`

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

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

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

## api-readByExternalId

`POST /org2/counterparty/api-readByExternalId`

Identifies a counterparty by their 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 counterparty in the external system (e.g., user ID on the website, database key, login). |

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

## api-readExternalIdsList

`POST /org2/counterparty/api-readExternalIdsList`

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

**Тіло запиту (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. |
| `counterpartyUuid` | string (uuid) |  | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |

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

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

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

## api-readWithoutExternalId

`POST /org2/counterparty/api-readWithoutExternalId`

Retrieves a list of counterparties 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`**

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

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

## api-deleteExternalId

`POST /org2/counterparty/api-deleteExternalId`

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

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

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

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