Оплати і витрати через API: оплата покупця, повернення, витрати

Що будуємо

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

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

Крок	Метод	Навіщо
1	bankAccounts/api-readList і cashRegistry/api-readList	Отримати uuid рахунків і кас — це значення поля paymentEntity
2	currency/api-readList	Отримати uuid валюти документа
3	invoiceForCustomerPayment/api-readByExternalId	Знайти замовлення покупця, яке оплачується (Синхронізація замовлень)
4	customerPayment/api-create	Створити оплату від покупця на замовлення
5	customerPayment/api-readList	Перевірити, чи оплата вже є (фільтр orders)
6	refundToCustomer/api-create	Повернути кошти покупцю
7	otherExpenses/api-create	Записати витрату (комісія еквайрингу, доставка тощо)
8	interaccountTransfer/api-create	Перенести кошти між касами і рахунками
9	customerPayment/api-cancel	Скасувати помилкову оплату

Як створити оплату від покупця

customerPayment/api-create вимагає покупця counterparty і валюту currency. Зв’язок із замовленням задає масив paymentDetails: кожен елемент містить invoiceForCustomerpayment (uuid замовлення покупця; зверніть увагу на написання поля — з малою літерою p) і payed (сума). Касу або рахунок вказує paymentEntity.

curl -X POST https://app.bimpsoft.com/org2/customerPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "<buyer-uuid>",
    "currency": "<uah-currency-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-06T10:40:00",
    "number": "myshop-10452",
    "comment": "Оплата карткою, замовлення myshop №10452",
    "commission": 62,
    "paymentDetails": [
      { "invoiceForCustomerpayment": "<order-uuid>", "payed": 12400 }
    ]
  }'

Відповідь: { "success": true, "data": { "uuid": "<payment-uuid>" } }.

Поле commission — комісія платіжної системи; calculationRate (в елементі paymentDetails) — крос-курс, якщо валюта оплати відрізняється від валюти замовлення (Одна оплата на кілька замовлень у різних валютах). Після збереження в замовленні збільшується sumPayed, а залишок до сплати зменшується.

Оплата кількох замовлень одним платежем. Додайте елементи в paymentDetails:

"paymentDetails": [
  { "invoiceForCustomerpayment": "<order-1-uuid>", "payed": 5000 },
  { "invoiceForCustomerpayment": "<order-2-uuid>", "payed": 7400 }
]

Аванс і переплата. Правила обліку авансів і переплат описані в статті Оплата від покупця, аванси та переплати.

Як змінити або скасувати оплату

customerPayment/api-update приймає uuid і поля, що змінюються (number, comment, date, paymentEntity, commission, currency, paymentDetails). customerPayment/api-cancel з uuid скасовує документ. Статуси оплат повертає customerPayment/api-readStatuses.

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

Для оплат у специфікації немає методів зовнішніх ID, тому захищайтеся так:

1. Передавайте ID платежу вашої платіжної системи в number або comment документа.
2. Перед створенням оплати викличте customerPayment/api-readList з фільтром orders: ["<order-uuid>"] і періодом у periodable. Якщо платіж з таким number уже є — не створюйте.
3. Створюйте оплату лише після підтвердження платежу вашою платіжною системою, а не при оформленні замовлення.
4. Ведіть у своїй базі пару «ID платежу — uuid оплати Bimp».

Замовлення, до якого належить оплата, знаходьте за зовнішнім ID, а не за номером документа: Зовнішні ID.

Як повернути кошти покупцю

refundToCustomer/api-create вимагає: expenseItem (стаття витрат), customer, organization, paymentEntity, author і масив paymentDetails з елементами invoice (замовлення покупця) та refundSum. Статті витрат — expenseItems/api-readList.

curl -X POST https://app.bimpsoft.com/org2/refundToCustomer/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expenseItem": "<expense-item-uuid>",
    "customer": "<buyer-uuid>",
    "organization": "<organization-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "author": "<employee-uuid>",
    "documentSum": 3100,
    "paymentDetails": [ { "invoice": "<order-uuid>", "refundSum": 3100 } ]
  }'

Повернення товару від покупця — окремий документ (customer-inventories-return/api-create), а грошове повернення оформлюється refundToCustomer. Обидва кроки описані в статтях Повернення товару від покупця та Повернення коштів покупцю.

Як записати витрату або дохід

otherExpenses/api-create фіксує витрату, не пов’язану із закупівлею товару: organization, expenseItem, paymentEntity обов’язкові, а в paymentDetails для кожного рядка — sum, project, lineOfBusiness, expenseItem (за потреби invoiceForCustomerPayment, щоб віднести витрату на замовлення).

curl -X POST https://app.bimpsoft.com/org2/otherExpenses/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": "<organization-uuid>",
    "expenseItem": "<expense-item-uuid>",
    "paymentEntity": "<bank-account-uuid>",
    "date": "2026-11-06T11:00:00",
    "comment": "Комісія еквайрингу за 05.11",
    "paymentDetails": [
      {
        "sum": 186,
        "expenseItem": "<expense-item-uuid>",
        "project": "<project-uuid>",
        "lineOfBusiness": "<line-of-business-uuid>"
      }
    ]
  }'

Аналогічно otherIncome/api-create записує інший дохід (incomeItem, статті доходів — incomeItems/api-readList). Правила обліку витрат — Витрати періоду, податки та інші витрати. Заявку на витрату (план платежу) створює expenseRequest/api-create.

Як перенести кошти між рахунками

interaccountTransfer/api-create вимагає organization, paymentEntitySender, paymentEntityRecipient, sum, project і lineOfBusiness. Для переказу між рахунками в різних валютах додайте currency, purchaseCurrency, rate і amountToCredit. Залишки на рахунках і в касах повертає financing-balance/api-readList — див. Залишок коштів на рахунках і в касах.

Вебхуки і опитування

Окремого вебхука на оплати немає: типи вебхуків — inventory_balance, product_upsert і order_status (Вебхуки). Про зміну оплати вашу систему сповістить подія order_status, якщо статус замовлення змінюється при оплаті, а в тілі події є sumPayed. Інакше раз на кілька хвилин викликайте customerPayment/api-readList з періодом periodable і фільтром orders.

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

Оплата створилась, але замовлення не позначено оплаченим. Причина: у paymentDetails не вказано invoiceForCustomerpayment або вказано інше замовлення. Рішення: перевірте написання поля і uuid; зверніть увагу, що поле називається invoiceForCustomerpayment, а не invoiceForCustomerPayment.

Помилка валідації currency. Причина: передано код валюти (UAH) замість uuid. Рішення: візьміть uuid із currency/api-readList.

Не знайдено paymentEntity. Причина: передано uuid рахунку іншої організації або не uuid. Рішення: використовуйте uuid з bankAccounts/api-readList або cashRegistry/api-readList.

Подвійна оплата після повтору запиту. Причина: api-create повторили без перевірки. Рішення: правила в розділі «Як не створити дублі оплат»; зайву оплату скасуйте методом customerPayment/api-cancel.

Помилка 429. Перевищено ліміт запитів, див. Ліміти.