# Закупівлі через API: від замовлення постачальнику до оплати

URL: https://bimpsoft.com/help/developers/purchasing-via-api/
Updated: 2026-11-06

> Ланцюжок закупівлі в API повторює інтерфейс: замовлення постачальнику (invoiceForSupplierPayment/api-create), надходження (purchaseInvoice/api-create з посиланням на замовлення) і оплата постачальнику (paymentToSupplier/api-create з paymentDetails). Кожен документ створюється окремим запитом, а скасовується методом api-cancel.

## Що будуємо

Автоматизація закупівель: система планування, ERP чи інтеграція з постачальником створює в Bimp замовлення постачальнику, фіксує надходження товарів і оплати. Логіка документів описана в статтях [Замовлення постачальнику](https://bimpsoft.com/help/purchasing/purchase-order/), [Надходження товарів і послуг](https://bimpsoft.com/help/purchasing/goods-receipt/) і [Оплата постачальнику](https://bimpsoft.com/help/purchasing/supplier-payment/). Нижче — ті самі кроки на рівні API. Токен компанії передається в заголовку `access-token` ([Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)).

Відповідність термінів:

| В інтерфейсі | У API |
|---|---|
| Замовлення постачальнику | `invoiceForSupplierPayment` |
| Надходження товарів і послуг | `purchaseInvoice` |
| Оплата постачальнику | `paymentToSupplier` |
| Повернення товарів постачальнику | `refundSupplier` |

## Які методи і в якому порядку

| Крок | Метод | Навіщо |
|---|---|---|
| 1 | [`counterparty/api-readList`](/help/developers/api-reference/counterparty/#api-read-list) (`types: ["isSupplier"]`) | Знайти постачальника; при відсутності — `counterparty/api-insert` з `isSupplier: true` |
| 2 | [`contract/api-readList`](/help/developers/api-reference/contract/#api-read-list) | Знайти договір із постачальником |
| 3 | [`organization/api-readList`](/help/developers/api-reference/organization/#api-read-list), [`warehouse/api-readList`](/help/developers/api-reference/warehouse/#api-read-list), [`project/api-readList`](/help/developers/api-reference/project/#api-read-list), [`lineOfBusiness/api-readList`](/help/developers/api-reference/line-of-business/#api-read-list) | Отримати довідкові значення для документа |
| 4 | [`invoiceForSupplierPayment/api-create`](/help/developers/api-reference/invoice-for-supplier-payment/#api-create) | Створити замовлення постачальнику з позиціями |
| 5 | [`purchaseInvoice/api-create`](/help/developers/api-reference/purchase-invoice/#api-create) | Оприбуткувати товар на склад [на підставі](https://bimpsoft.com/help/basics/create-based-on/) замовлення |
| 6 | [`paymentToSupplier/api-create`](/help/developers/api-reference/payment-to-supplier/#api-create) | Оплатити замовлення постачальнику |
| 7 | [`refundSupplier/api-create`](/help/developers/api-reference/refund-supplier/#api-create) | За потреби повернути товар постачальнику |
| 8 | `invoiceForSupplierPayment/api-readList`, `purchaseInvoice/api-readList`, `paymentToSupplier/api-readList` | Контролювати стан: що замовлено, отримано й оплачено |

## Як створити замовлення постачальнику

Метод `invoiceForSupplierPayment/api-create` вимагає постачальника `counterparty`, договір `contract`, організацію `organization`, [склад](https://bimpsoft.com/help/inventory/warehouses/) `warehouse`, проєкт `project` та автора `author`. Позиції передаються масивом `products`; для кожного рядка обов'язкові `nomenclature`, `quantity`, `price`, `lineOfBusiness`, `project` і `unitOfMeasurment`.

```bash
curl -X POST https://app.bimpsoft.com/org2/invoiceForSupplierPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<supplier-uuid>",
    "contract": "<contract-uuid>",
    "organization": "<organization-uuid>",
    "warehouse": "<warehouse-uuid>",
    "project": "<project-uuid>",
    "author": "<employee-uuid>",
    "date": "2026-11-06T09:00:00",
    "automaticPaymentsPlanning": true,
    "products": [
      {
        "nomenclature": "<product-uuid>",
        "quantity": 100,
        "price": 85.5,
        "unitOfMeasurment": "<unit-uuid>",
        "lineOfBusiness": "<line-of-business-uuid>",
        "project": "<project-uuid>"
      }
    ]
  }'
```

Відповідь: `{ "success": true, "data": { "uuid": "<supplier-order-uuid>" } }`. Прапорець `automaticPaymentsPlanning: true` додає документ у платіжний календар. У рядку можна передати `invoiceForCustomerPayment` — [замовлення покупця](https://bimpsoft.com/help/sales/customer-order/), під яке закуповується товар (закупівля «під замовлення»), а також `supplierNomenclature` — назву товару в постачальника. Зіставлення назв описано в статті [Номенклатура постачальника](https://bimpsoft.com/help/purchasing/supplier-products/).

Статуси замовлення постачальнику повертає `invoiceForSupplierPayment/api-readStatuses`.

## Як оприбуткувати товар

`purchaseInvoice/api-create` створює документ надходження на підставі замовлення постачальнику. Обов'язкові поля шапки: `organization`, `responsible`, `counterparty`, `warehouse`, `contract`, `invoiceForSupplierPayment`, прапорці обліку `VATaccounted`, `costWithoutVAT`, `bookkeperAccounting`, `managerialAccounting`, `taxAccounting` та масив `products`.

Для кожного рядка `products` обов'язкові: `product`, `orderedCount` (замовлено), `warehouseCount` (фактично отримано), `cost`, `sum`, `VATsum`, `lineOfBusiness`, `project` та `invoiceForCustomerPayment` (може бути `null`).

```bash
curl -X POST https://app.bimpsoft.com/org2/purchaseInvoice/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<organization-uuid>",
    "responsible": "<employee-uuid>",
    "counterparty": "<supplier-uuid>",
    "warehouse": "<warehouse-uuid>",
    "contract": "<contract-uuid>",
    "invoiceForSupplierPayment": "<supplier-order-uuid>",
    "date": "2026-11-10T12:00:00",
    "VATaccounted": false,
    "costWithoutVAT": false,
    "bookkeperAccounting": true,
    "managerialAccounting": true,
    "taxAccounting": false,
    "products": [
      {
        "product": "<product-uuid>",
        "orderedCount": 100,
        "warehouseCount": 98,
        "cost": 85.5,
        "sum": 8379,
        "VATsum": 0,
        "lineOfBusiness": "<line-of-business-uuid>",
        "project": "<project-uuid>",
        "invoiceForCustomerPayment": null
      }
    ]
  }'
```

Тут отримано 98 з 100 замовлених: різницю `orderedCount` − `warehouseCount` видно в документі як недопоставку. Після збереження товар збільшує залишок на складі `warehouse`, а [собівартість](https://bimpsoft.com/help/costing/cost-price-guide/) рахується за правилами обліку — Надходження товарів і послуг. Для зміни використовуйте `purchaseInvoice/api-update`.

## Як оплатити постачальнику

`paymentToSupplier/api-create` вимагає `counterparty` і `currency`. Сума й призначення задаються масивом `paymentDetails`: у кожному елементі — `invoiceForSupplierPayment` (замовлення постачальнику) та `payed` (сума оплати). Каса або банківський рахунок передається полем `paymentEntity` — його значення беруть із [`bankAccounts/api-readList`](/help/developers/api-reference/bank-accounts/#api-read-list) або [`cashRegistry/api-readList`](/help/developers/api-reference/cash-registry/#api-read-list).

```bash
curl -X POST https://app.bimpsoft.com/org2/paymentToSupplier/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<supplier-uuid>",
    "currency": "<currency-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-12T10:00:00",
    "comment": "Оплата за замовленням постачальнику",
    "paymentDetails": [
      { "invoiceForSupplierPayment": "<supplier-order-uuid>", "payed": 8379 }
    ]
  }'
```

Одна оплата може закривати кілька замовлень: додайте ще елементи в `paymentDetails`. Для оплат у валюті є поле `calculationRate` (крос-курс) у кожному елементі. Деталі про оплати — у статті [Оплати і витрати через API](https://bimpsoft.com/help/developers/payments-via-api/).

## Як повернути товар постачальнику

`refundSupplier/api-create` створює повернення на підставі надходження: `baseDocument` — uuid документа надходження, `products` — масив із `nomenclature`, `count`, `cost` (за потреби `VAT`). Додатково можна передати `warehouse`, `responsible`, `date`, `comment`. Повернення коштів від постачальника — окремий документ `refundFromSupplier`. Бізнес-правила — [Повернення товарів постачальнику](https://bimpsoft.com/help/purchasing/supplier-return/).

## Як не створити дублі

У специфікації API немає методів зовнішніх ID для документів закупівлі (вони є для замовлень покупця, відвантажень, товарів і контрагентів — [Зовнішні ID](https://bimpsoft.com/help/developers/api-external-ids/)). Тому зв'язок із вашою системою зберігайте так:

1. Передавайте ваш номер у полі `number` документа (замовлення постачальнику, надходження) і ведіть у своїй базі пару «ваш ID — `uuid` Bimp». 
2. Після `api-create` одразу записуйте отриманий `uuid` у свою базу, до наступних кроків.
3. Перед повторним створенням після збою перевіряйте `api-readList` за періодом (`periodable` для надходжень і оплат, фільтр `date` для замовлень постачальнику) і порівнюйте `number` або `comment`.
4. Постачальників зіставляйте через `counterparty/api-saveExternalId`, товари — через `nomenclature/api-saveExternalId`.

## Типові помилки

**Надходження не створюється, помилка обов'язкового поля.** Причина: не передано `invoiceForSupplierPayment` або одне з п'яти полів обліку (`VATaccounted`, `costWithoutVAT`, `bookkeperAccounting`, `managerialAccounting`, `taxAccounting`). Рішення: передайте всі обов'язкові поля шапки і рядків.

**Оплата створена, але замовлення не вважається оплаченим.** Причина: у `paymentDetails` вказано не те замовлення або суму `payed` менше за суму замовлення. Рішення: перевірте `invoiceForSupplierPayment` і суму; залишок видно у відповіді (`remainder`).

**Документ не вдається змінити.** Якщо `api-update` відхиляє зміни, скасуйте документ методом `api-cancel` і створіть виправлений. 

**Помилка 429.** Перевищено 15 запитів на секунду з IP, див. [Ліміти](https://bimpsoft.com/help/developers/api-limits/).

## FAQ

**Який метод API створює замовлення постачальнику?**

invoiceForSupplierPayment/api-create. У Bimp замовлення постачальнику — це документ «Рахунок на оплату постачальнику», в API він називається invoiceForSupplierPayment.

**Чи можна створити надходження без замовлення постачальнику?**

У специфікації purchaseInvoice/api-create поле invoiceForSupplierPayment обов'язкове, тому надходження створюється на підставі замовлення постачальнику. Якщо замовлення немає, створіть його першим кроком.

**Як оплатити замовлення постачальнику через API?**

Викличте paymentToSupplier/api-create: вкажіть постачальника, валюту і в масиві paymentDetails — замовлення постачальнику та суму payed.

**Як скасувати документ закупівлі?**

Кожен документ має метод api-cancel: purchaseInvoice, invoiceForSupplierPayment, paymentToSupplier, refundSupplier. Передайте uuid документа.