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

Що таке зовнішній 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
Контрагенти	/org2/counterparty/api-…ExternalId	counterpartyUuid	counterparty
Замовлення покупців	/org2/invoiceForCustomerPayment/api-…ExternalId	orderUuid	invoice-for-customer-payment
Реалізація	/org2/salesInvoice/api-…ExternalId	salesInvoiceUuid	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), див. Ліміти, пагінація і помилки.

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

Ресурс	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:

   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. Збережіть зв’язок:

   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"}'

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

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

   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"}'

Повні сценарії — у статтях Синхронізація замовлень з інтернет-магазином і Синхронізація каталогу товарів.

Як видалити зв’язок

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

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"}'