# Зовнішні ID в API Bimp: зіставлення об'єктів з вашою системою

URL: https://bimpsoft.com/help/developers/api-external-ids/
Updated: 2026-11-06

> Зовнішній ID — це пара «source + externalId», яка зв'язує об'єкт Bimp (UUID) з ідентифікатором у вашому магазині чи маркетплейсі. Шість методів із суфіксом ExternalId доступні для чотирьох ресурсів: номенклатура, контрагент, замовлення покупця і реалізація. Зв'язок створює api-saveExternalId.

## Що таке зовнішній ID

Зовнішній ID — це зв'язок між об'єктом Bimp і його ідентифікатором у вашій системі, записаний як пара `source` + `externalId`. Завдяки йому інтеграція не зберігає у себе UUID Bimp: вона шукає об'єкт Bimp за власним ідентифікатором і створює зв'язок після першого імпорту. Типові приклади — ID товару на сайті, ID користувача в магазині, номер замовлення маркетплейсу.

Поля зв'язку:

| Поле | Що означає |
|---|---|
| `source` | Ідентифікатор зовнішньої системи (`prom`, `rozetka`, `shopify`). Нечутливий до регістру: значення обрізається і переводиться в нижній регістр |
| `externalId` | Ідентифікатор об'єкта в зовнішній системі (рядок) |
| UUID об'єкта Bimp | У запиті називається за ресурсом (див. таблицю нижче) |

Для одного об'єкта Bimp можна зберігати окремий `externalId` для кожного `source`.

## Для яких ресурсів доступні зовнішні ID

Зовнішні ID підтримують чотири ресурси; всі шляхи починаються з `/org2/`, методи — `POST`.

| Ресурс | Шлях | Параметр UUID об'єкта | Довідник |
|---|---|---|---|
| Номенклатура (товари) | `/org2/nomenclature/api-…ExternalId` | `nomenclatureUuid` | [nomenclature](/help/developers/api-reference/nomenclature/) |
| Контрагенти | `/org2/counterparty/api-…ExternalId` | `counterpartyUuid` | [counterparty](/help/developers/api-reference/counterparty/) |
| [Замовлення покупців](https://bimpsoft.com/help/sales/customer-order/) | `/org2/invoiceForCustomerPayment/api-…ExternalId` | `orderUuid` | [invoice-for-customer-payment](/help/developers/api-reference/invoice-for-customer-payment/) |
| Реалізація | `/org2/salesInvoice/api-…ExternalId` | `salesInvoiceUuid` | [sales-invoice](/help/developers/api-reference/sales-invoice/) |

Повний перелік шляхів для кожного ресурсу — `api-saveExternalId`, `api-readExternalId`, `api-readByExternalId`, `api-readExternalIdsList`, `api-readWithoutExternalId`, `api-deleteExternalId`.

## Які методи є

Усі шість методів працюють однаково для кожного ресурсу. Нижче `<uuidField>` — параметр із таблиці вище.

| Метод | Що робить | Тіло запиту | `data` у відповіді |
|---|---|---|---|
| `api-saveExternalId` | Створює або оновлює зв'язок | `<uuidField>`, `source`, `externalId` (усі обов'язкові) | `{"success": true}` |
| `api-readExternalId` | Повертає зовнішній ID об'єкта для `source` | `<uuidField>`, `source` (обов'язкові) | `{"externalId": "..."}` або `null` |
| `api-readByExternalId` | Знаходить об'єкт Bimp за зовнішнім ID | `source`, `externalId` (обов'язкові) | об'єкт Bimp (див. нижче) або `null`, якщо зв'язку немає |
| `api-readExternalIdsList` | Список зв'язків з фільтрами | `pagination` (обов'язковий), `source`, `<uuidField>` | масив зв'язків |
| `api-readWithoutExternalId` | Об'єкти без зв'язку для `source` | `pagination`, `source` (обов'язкові) | масив об'єктів Bimp |
| `api-deleteExternalId` | Видаляє зв'язок | `<uuidField>` (обов'язковий), `source` | `true` |

`pagination` має вигляд `{"offset": 0, "count": 100}` (максимум `count` — 100), див. [Ліміти, пагінація і помилки](https://bimpsoft.com/help/developers/api-limits/).

Що повертають методи читання за ресурсами:

| Ресурс | `readByExternalId` і `readExternalIdsList` | `readWithoutExternalId` |
|---|---|---|
| Номенклатура | `readByExternalId`: `nomenclatureUuid`, `name`; список: `nomenclatureUuid`, `name`, `source`, `externalId` | `nomenclatureUuid`, `name` |
| Контрагент | `readByExternalId`: `counterpartyUuid`, `name`; список: `counterpartyUuid`, `name`, `source`, `externalId` | `counterpartyUuid`, `name` |
| Замовлення покупця | `orderUuid`, `date`, `number`, `source`, `externalId` | `orderUuid`, `number`, `date`, `amount`, `comment`, `counterpartyName`, `counterpartyUuid`, `currency`, `statusName` |
| Реалізація | `salesInvoiceUuid`, `date`, `number`, `source`, `externalId` | `salesInvoiceUuid`, `number`, `date`, `amount`, `comment`, `counterpartyName`, `counterpartyUuid`, `currency` (перелік може бути повнішим) |

## Як зіставити замовлення з вашою системою

Типовий потік для замовлень покупців виглядає так, а для товарів і контрагентів він ідентичний.

1. Для нового замовлення з магазину перевірте, чи воно вже є в Bimp. Викличте `api-readByExternalId`:

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

   Відповідь `{"success": true, "data": null}` означає, що замовлення ще не імпортоване.

2. Створіть замовлення методом `/org2/invoiceForCustomerPayment/api-create` — див. довідник.
3. Збережіть зв'язок:

   ```bash
   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"orderUuid": "<ORDER_UUID>", "source": "myshop", "externalId": "ORD-10452"}'
   ```

   ```json
   { "success": true, "data": { "success": true } }
   ```

4. Щоб знайти замовлення, які ще не зіставлені з вашою системою, викличте `api-readWithoutExternalId`:

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

Повні сценарії — у статтях [Синхронізація замовлень з інтернет-магазином](https://bimpsoft.com/help/developers/sync-orders/) і [Синхронізація каталогу товарів](https://bimpsoft.com/help/developers/sync-catalog/).

## Як видалити зв'язок

Метод `api-deleteExternalId` видаляє зв'язок для вказаного `source`. Якщо `source` не передати, видаляються всі зовнішні зв'язки цього об'єкта. Метод повертає `true`, і коли зв'язок видалено, і коли його не було.

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-deleteExternalId \
  -H "access-token: <COMPANY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"nomenclatureUuid": "<NOMENCLATURE_UUID>", "source": "prom"}'
```

> [!WARNING] Без параметра `source` метод `api-deleteExternalId` видаляє зв'язки з усіма зовнішніми системами для цього об'єкта.

## FAQ

**Для яких об'єктів Bimp підтримуються зовнішні ID?**

Для чотирьох ресурсів: номенклатура (nomenclature), контрагент (counterparty), замовлення покупця (invoiceForCustomerPayment) і реалізація (salesInvoice). Для кожного доступні однакові шість методів.

**Що таке параметр source?**

Ідентифікатор зовнішньої системи, наприклад prom або rozetka. Значення нечутливе до регістру: Bimp обрізає пробіли й переводить його в нижній регістр. Один об'єкт може мати окремий зовнішній ID для кожного source.

**Як знайти об'єкти, які ще не зіставлені з моєю системою?**

Викличте readWithoutExternalId відповідного ресурсу з параметрами pagination і source. Метод повертає об'єкти, для яких немає зв'язку з цим source.

**Що повертає readByExternalId, якщо зв'язку немає?**

Успішну відповідь з data: null, а не помилку.