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

Що будуємо

Автоматизація закупівель: система планування, ERP чи інтеграція з постачальником створює в Bimp замовлення постачальнику, фіксує надходження товарів і оплати. Логіка документів описана в статтях Замовлення постачальнику, Надходження товарів і послуг і Оплата постачальнику. Нижче — ті самі кроки на рівні API. Токен компанії передається в заголовку access-token (Початок роботи з API).

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

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

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

Крок	Метод	Навіщо
1	counterparty/api-readList (types: ["isSupplier"])	Знайти постачальника; при відсутності — counterparty/api-insert з isSupplier: true
2	contract/api-readList	Знайти договір із постачальником
3	organization/api-readList, warehouse/api-readList, project/api-readList, lineOfBusiness/api-readList	Отримати довідкові значення для документа
4	invoiceForSupplierPayment/api-create	Створити замовлення постачальнику з позиціями
5	purchaseInvoice/api-create	Оприбуткувати товар на склад на підставі замовлення
6	paymentToSupplier/api-create	Оплатити замовлення постачальнику
7	refundSupplier/api-create	За потреби повернути товар постачальнику
8	invoiceForSupplierPayment/api-readList, purchaseInvoice/api-readList, paymentToSupplier/api-readList	Контролювати стан: що замовлено, отримано й оплачено

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

Метод invoiceForSupplierPayment/api-create вимагає постачальника counterparty, договір contract, організацію organization, склад warehouse, проєкт project та автора author. Позиції передаються масивом products; для кожного рядка обов’язкові nomenclature, quantity, price, lineOfBusiness, project і unitOfMeasurment.

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 — замовлення покупця, під яке закуповується товар (закупівля «під замовлення»), а також supplierNomenclature — назву товару в постачальника. Зіставлення назв описано в статті Номенклатура постачальника.

Статуси замовлення постачальнику повертає 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).

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, а собівартість рахується за правилами обліку — Надходження товарів і послуг. Для зміни використовуйте purchaseInvoice/api-update.

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

paymentToSupplier/api-create вимагає counterparty і currency. Сума й призначення задаються масивом paymentDetails: у кожному елементі — invoiceForSupplierPayment (замовлення постачальнику) та payed (сума оплати). Каса або банківський рахунок передається полем paymentEntity — його значення беруть із bankAccounts/api-readList або cashRegistry/api-readList.

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.

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

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

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

У специфікації API немає методів зовнішніх ID для документів закупівлі (вони є для замовлень покупця, відвантажень, товарів і контрагентів — Зовнішні ID). Тому зв’язок із вашою системою зберігайте так:

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, див. Ліміти.