Документація API/Продажі/Платежі

Платежі

Надходження грошей від клієнтів: оплата рахунку чи замовлення, передоплата. Платіж змінює залишок каси чи рахунку й робить проводки. Право ролі: payment.

Маршрути

GET/payment

Список платежів з пагінацією, фільтрами й total.

право: payment.view2 очк.

GET/payment/{id}

Одна картка.

право: payment.view1 очк.

POST/payment

Створити.

право: payment.create10 очк.

PUT/payment/{id}

Оновити.

право: payment.update10 очк.

DELETE/payment/{id}

Видалити.

право: payment.delete10 очк.

Видалений платіж зникає остаточно, маршруту /payment/deleted немає.

Усі поля

Обов’язкові name, balance_id, category_id, currency_id (= валюта гаманця), exchange_rate і amount (більше нуля). Платником може бути не більше одного з contact_id / account_id, а з invoice_id обов’язково один. Якщо owner_id не передано, відповідальним стає користувач токена.

exchange_rate: курс до валюти рахунку, а не до гривніtotal = amount × exchange_rate зараховується в оплату рахунку у валюті рахунку. Для платежу в тій самій валюті, що й рахунок (або без рахунку), це завжди "1"; інше значення при однакових валютах дає 422. Для гривневого платежу на рахунок у доларах це курс гривні до долара, напр. "0.024242" при 41,25 грн/$. Гривневий еквівалент для обліку сервер рахує сам за курсом дня, його не передають.

Якщо balance_id чи category_id немає в довіднику, буде 422. Роль, що бачить платежі «лише свої», отримує в списку тільки записи, де вона відповідальна.

Що змінюється після створенняPUT змінює лише гроші й облік: amount, exchange_rate, currency_id, balance_id, category_id, date, owner_id, платника (contact_id / account_id), description і доп. поля. name, provider_id, invoice_id, order_id після створення не змінюються. Щоб перенести оплату на інший документ, видаліть платіж і створіть новий. Зміна суми перепроводить платіж (сторно + нова проводка).

Поле	Тип	Обмеження	Опис
`name`обов.	рядок	≤ 60 симв.	Назва платежу. {{next_id}} замінюється на наступний номер. Після створення не змінюється.
`balance_id`обов.	id		Каса або банківський рахунок (/balance).
`category_id`обов.	id		Стаття доходу (/fin-account/search?type=revenue).
`amount`	ціле, копійки		Сума у валюті гаманця, копійки.
`exchange_rate`	десяткове (рядок)		Обов’язковий. Курс валюти платежу до валюти рахунку; без рахунку чи в тій самій валюті передавайте "1".
`date`	дата-час		Дата надходження. Якщо не передано, поточний час.
`currency_id`	id		Обов’язковий. Валюта платежу = валюта гаманця.
`status_id`	id		Статус.
`provider_id`	id		Ваша юрособа-отримувач. Після створення не змінюється.
`owner_id`	id		Відповідальний користувач (/user). Якщо не передано, це користувач токена.
`order_id`	id		Замовлення, що оплачується. Після створення не змінюється.
`invoice_id`	id		Рахунок, що оплачується. Тоді обов’язковий платник (рівно одне з contact_id / account_id), а гаманець має належати тій самій юрособі, що й рахунок. Після створення не змінюється.
`account_id`	id		Платник-контрагент (не разом з contact_id).
`contact_id`	id		Платник-контакт (не разом з account_id).
`description`	рядок	≤ 1024 симв.	Опис / коментар.
`create_receipt`	bool		Створити фіскальний чек (якщо підключено ПРРО).
`receipt_payment_method`	рядок		Спосіб оплати для чека.
`id`лише читання	ціле		Ідентифікатор запису.
`total`лише читання	ціле, копійки		Сума у валюті рахунку = amount × exchange_rate, рахує сервер.
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`created_by_id`лише читання	id		Хто створив запис.
`sub`лише читання	рядок		Службове поле, ігноруйте.

Вкладені масиви

extra_fields: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.

Повʼязані обʼєкти для ?expand= (11)

Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.

Currency → CurrencyStatus → LookupBalance → BalanceCategory → FinanceAccountProvider → AccountOwner → UserOrder → OrderInvoice → InvoiceAccount → AccountContact → ContactCreatedBy → User

Службові поля у відповіді, ігноруйте: OldPayment.

Приклад

Оплата рахунку 120 на банківський рахунок

POST /api/v1/payment
Idempotency-Key: bank-tx-2026-09-30-8841

{
  "name": "Оплата рахунку №120",
  "invoice_id": 120,
  "account_id": 12,
  "balance_id": 2,
  "category_id": 9,
  "amount": 1500000,
  "currency_id": 1,
  "exchange_rate": "1",
  "date": "2026-09-30T00:00:00+03:00"
}

Обов’язково Idempotency-KeyПовтор створення платежу без ключа дасть подвійне надходження в обліку. Для імпорту банківських виписок передавайте ключем id транзакції банку.