Платежі через API

Платежі через API використовують для передавання касових і банківських операцій у Skynum: оплат від покупців, оплат постачальникам, витрат, переказів між касами й рахунками, вхідних залишків, податків та інших фінансових операцій.

Платіж сам по собі відповідає за рух грошей. Якщо платіж має закривати документ, його потрібно повʼязати з документом через binds або використовувати автоматичне звʼязування, якщо сценарій це дозволяє.

Повʼязані інструкції:

• Створення платежу;
• Повʼязані платежі;
• Каси;
• Банківські рахунки;
• Вхідні фінансові залишки;
• Банківські виписки;
• Документи через API;
• Ліміти та безпечна робота з API.

Endpoint-и платежів

Метод	Endpoint	Призначення
GET	/v1/payments	отримати список платежів
POST	/v1/payments	створити платіж
GET	/v1/payments/:id	отримати один платіж
PUT	/v1/payments/:id	оновити платіж
DELETE	/v1/payments/:id	видалити платіж
PUT	/v1/payments/:id/activate	активувати платіж
PUT	/v1/payments/:id/deactivate	деактивувати платіж

Типи платіжних документів

Поле typedoc визначає форму платіжного документа. Для POST /v1/payments це обовʼязкове поле.

API платежів підтримує такі типи:

typedoc	Назва в Skynum	Призначення
bank_in	Вхідне платіжне доручення	Надходження коштів на банківський рахунок.
bank_out	Вихідне платіжне доручення	Списання коштів з банківського рахунку.
cash_in	Прибутковий касовий ордер	Надходження готівки в касу.
cash_out	Видатковий касовий ордер	Видача готівки з каси.
cash_conversion	Конвертація готівки	Обмін готівки між валютами.
bank_conversion	Конвертація безготівкова	Обмін коштів між валютами на банківських рахунках.

Типи платежів

Поле typepayment визначає економічний зміст платежу. Воно відповідає тому, з ким або з чим повʼязана фінансова операція.

typepayment	Назва	Типовий payment_subject_type
settlement_with_clients	Розрахунки з покупцями	Contragent
settlement_with_suppliers	Розрахунки з постачальниками	Contragent
expense	Витрати	Expense
money_on_way	Гроші в дорозі	Contragent
encashment	Інкасація	Bankbox
cash_from_bank	Готівка з банку	Bankbox
founder	Засновник	Founder
cashbox_transfer	Передача в касу	Cashbox
initial_cash_remain	Вхідний залишок по касі	Cashbox
initial_bank_remain	Вхідний залишок по банку	Bankbox
initial_client_debt	Початкова заборгованість покупця/покупцю	Contragent
initial_debt_to_supplier	Початкова заборгованість постачальника/постачальнику	Contragent
bankbox_transfer	Передача в банк	Bankbox
universal	Універсальний	залежить від сценарію
nds	Оплата ПДВ	Agency
expense_creditors	Кредитори за витратами	Contragent
taxes	Інші податки	Tax
debtors_creditors	Дебітори та кредитори	Contragent
settlement_with_employees	Розрахунки зі співробітниками	Employee
salary_taxes	Зарплатні податки та збори	використовується для зарплатних податків

Набір допустимих typepayment також залежить від конкретного typedoc. Наприклад, для банківського вихідного платежу доступний ширший перелік типів, ніж для касового прихідного платежу.

Доступні типи платежів за документом

Для API важливо передавати не тільки правильний typedoc, а й typepayment, який підтримується для цього платіжного документа.

typedoc	typepayment	Назва
bank_out	settlement_with_clients	Розрахунки з покупцями
bank_out	settlement_with_suppliers	Розрахунки з постачальниками
bank_out	founder	Засновник
bank_out	expense	Витрати
bank_out	salary_taxes	Зарплатні податки та збори
bank_out	bankbox_transfer	Передача в банк
bank_out	nds	Оплата ПДВ
bank_out	expense_creditors	Кредитори за витратами
bank_out	debtors_creditors	Дебітори та кредитори
bank_out	taxes	Інші податки
bank_out	money_on_way	Гроші в дорозі
bank_in	settlement_with_clients	Розрахунки з покупцями
bank_in	settlement_with_suppliers	Розрахунки з постачальниками
bank_in	founder	Засновник
bank_in	bankbox_transfer	Передача в банк
bank_in	nds	Оплата ПДВ
bank_in	debtors_creditors	Дебітори та кредитори
bank_in	money_on_way	Гроші в дорозі
cash_in	settlement_with_clients	Розрахунки з покупцями
cash_in	settlement_with_suppliers	Розрахунки з постачальниками
cash_in	founder	Засновник
cash_in	cash_from_bank	Готівка з банку
cash_in	cashbox_transfer	Передача в касу
cash_in	debtors_creditors	Дебітори та кредитори
cash_in	settlement_with_employees	Розрахунки зі співробітниками
cash_out	settlement_with_clients	Розрахунки з покупцями
cash_out	settlement_with_suppliers	Розрахунки з постачальниками
cash_out	founder	Засновник
cash_out	expense	Витрати
cash_out	encashment	Інкасація
cash_out	cashbox_transfer	Передача в касу
cash_out	expense_creditors	Кредитори за витратами
cash_out	debtors_creditors	Дебітори та кредитори
cash_out	settlement_with_employees	Розрахунки зі співробітниками

Для cash_conversion і bank_conversion використовуйте поля валюти, суми й конвертованої валюти.

попередження

Якщо typepayment не відповідає typedoc, API може не прийняти платіж або очистити субʼєкт платежу під час обробки. Для облікових інтеграцій краще явно зберігати мапу дозволених комбінацій на стороні інтеграції.

Отримання списку платежів

GET /v1/payments повертає список платежів. Параметр typedoc є обовʼязковим.

Підтримані фільтри:

Параметр	Призначення
typedoc	Тип платіжного документа. Обовʼязковий.
offset	Сторінка або зміщення списку. За замовчуванням 1.
limit	Кількість записів. За замовчуванням 100, максимум 1000.
date_from	Дата платежу від.
date_to	Дата платежу до.
query	Пошук за номером або кодом платежу.
contragent_id	Фільтр за контрагентом.
active	Фільтр за активністю.
typepayment	Фільтр за типом платежу.
cashbox_id	Фільтр за касою.
bankbox_id	Фільтр за банківським рахунком.
owner_id	Фільтр за власником.
executor_id	Фільтр за виконавцем.
updated_from	Оновлено від.
updated_to	Оновлено до.
with_custom_fields	Додати у відповідь додаткові поля.

Приклад:

GET /v1/payments?typedoc=cash_in&typepayment=settlement_with_clients&limit=100

Отримання одного платежу

GET /v1/payments/:id повертає один платіж за ID.

Додатково можна передати:

with_custom_fields=true

щоб отримати додаткові поля платежу.

Чернетка й активний платіж

Після створення платіж зберігається як чернетка. Чернетка не змінює фінансовий облік.

Щоб платіж провів рух коштів, його потрібно активувати:

PUT /v1/payments/:id/activate

У відповідях API важливі поля:

Поле	Що означає
active	Чи активований платіж.
docstate	Системний стан платежу.
status_id	Статус платежу з налаштувань компанії.
typedoc	Форма платіжного документа.
typepayment	Економічний тип платежу.

попередження

Активний платіж змінює фінансовий облік. Якщо платіж повʼязаний з документом, він також впливає на взаєморозрахунки за цим документом.

Створення платежу

Мінімально для створення платежу потрібен typedoc:

{
  "payment": {
    "typedoc": "cash_in"
  }
}

На практиці зазвичай передають:

• typedoc - тип платіжного документа;
• docdate - дату платежу;
• amount - суму;
• typepayment - тип платежу;
• cashbox_id або bankbox_id - касу або банківський рахунок;
• currency_id і currency_rate - валюту й курс;
• payment_subject_type і payment_subject - обʼєкт, з яким повʼязаний платіж;
• binds - звʼязки з документами, якщо платіж має закривати конкретні документи;
• custom_fields - додаткові поля, якщо вони налаштовані.

Приклад оплати від покупця готівкою:

{
  "payment": {
    "typedoc": "cash_in",
    "docdate": "2026-05-12",
    "amount": 1000,
    "typepayment": "settlement_with_clients",
    "cashbox_id": "cashbox-id",
    "currency_id": "currency-id",
    "currency_rate": 1,
    "payment_subject_type": "Contragent",
    "payment_subject": {
      "id": "contragent-id"
    }
  }
}

Поля для створення й оновлення платежу

Поле	Призначення
id	Внутрішній ID платежу. Використовується для наявного платежу, коли інтеграція передає вже відомий запис.
typedoc	Тип платіжного документа. Обовʼязкове поле для створення.
docdate	Дата платежу.
docnum	Номер платежу.
code	Код платежу.
api_id	Зовнішній ID інтеграції.
filial_id	Філія або юридична особа.
cashbox_id	Каса.
bankbox_id	Банківський рахунок.
currency_id	Валюта платежу.
currency_rate	Курс валюти.
amount	Сума платежу.
nds	Сума ПДВ.
typepayment	Тип платежу.
reason	Підстава.
annex	Додаток.
purpose	Призначення платежу.
converted_currency_id	Валюта, у яку виконується конвертація.
converted_amount	Сума після конвертації.
agreement_id	Договір.
payment_subject_type	Тип обʼєкта платежу.
payment_subject	Обʼєкт платежу.
subject_signify	Додатковий субʼєкт платежу для окремих сценаріїв, зокрема витрат.
disable_autobind	Вимкнути автоматичне звʼязування.
binds	Звʼязки з документами.
comments	Коментарі.
custom_fields	Додаткові поля.

Поля короткої відповіді платежу

GET /v1/payments повертає список платежів у короткому форматі.

Поле	Що означає
id	Внутрішній ID платежу.
typedoc	Тип платіжного документа.
note	Нотатка платежу.
docnum	Номер платежу.
typepayment	Тип платежу.
reason	Підстава.
annex	Додаток.
purpose	Призначення платежу.
api_id	Зовнішній ID інтеграції.
status_id	Статус платежу.
docstate	Системний стан платежу.
code	Код платежу.
filial_id	Філія або юридична особа.
executor_id	Виконавець.
owner_id	Власник.
source_document_type	Тип документа-джерела, якщо платіж створений з іншого процесу.
source_document_id	ID документа-джерела.
disable_autobind	Чи вимкнене автоматичне звʼязування.
agreement_id	Договір.
payment_subject_type	Тип субʼєкта платежу.
payment_subject_id	ID субʼєкта платежу.
subject_signify_id	ID додаткового субʼєкта платежу.
currency_id	Валюта платежу.
converted_currency_id	Валюта конвертації.
cashbox_id	Каса.
bankbox_id	Банківський рахунок.
docdate	Дата платежу.
active	Чи активований платіж.
currency_rate	Курс валюти.
amount	Сума платежу.
converted_amount	Сума конвертації.
nds	Сума ПДВ.
custom_fields	Додаткові поля, якщо передано with_custom_fields=true.
created_at	Дата створення.
updated_at	Дата оновлення.

Поля повної відповіді платежу

GET /v1/payments/:id і write-запити повертають повніший обʼєкт платежу.

Поле	Що означає
id	Внутрішній ID платежу.
typedoc	Тип платіжного документа.
docnum	Номер платежу.
code	Код платежу.
api_id	Зовнішній ID інтеграції.
note	Нотатка платежу.
reason	Підстава.
annex	Додаток.
purpose	Призначення платежу.
typepayment	Тип платежу.
status_id	Статус платежу.
docstate	Системний стан платежу.
filial_id	Філія або юридична особа.
executor_id	Виконавець платежу.
owner_id	Власник платежу.
source_document_type	Тип документа-джерела, якщо платіж створений з іншого процесу.
source_document_id	ID документа-джерела.
disable_autobind	Чи вимкнене автоматичне звʼязування.
agreement_id	Договір.
docdate	Дата платежу.
active	Чи активований платіж.
currency_id	ID валюти платежу.
currency_title	Назва валюти платежу.
currency_code	Код валюти платежу.
converted_currency_id	ID валюти конвертації.
converted_currency_title	Назва валюти конвертації.
converted_currency_code	Код валюти конвертації.
cashbox_id	ID каси.
cashbox_title	Назва каси.
bankbox_id	ID банківського рахунку.
bankbox_title	Назва банківського рахунку.
currency_rate	Курс валюти.
amount	Сума платежу.
converted_amount	Сума конвертації.
nds	Сума ПДВ.
payment_subject_type	Тип субʼєкта платежу.
payment_subject_id	ID субʼєкта платежу.
payment_subject_title	Назва субʼєкта платежу.
subject_signify_id	ID додаткового субʼєкта платежу.
subject_signify_title	Назва додаткового субʼєкта платежу.
comments	Коментарі.
binds	Звʼязки з документами.
custom_fields	Додаткові поля, якщо передано with_custom_fields=true.
created_at	Дата створення.
updated_at	Дата оновлення.

Каса або банківський рахунок

Для готівкових платежів використовується cashbox_id.

Для безготівкових платежів використовується bankbox_id.

Для конвертацій і переказів можуть використовуватися поля, повʼязані з касою, рахунком, валютою та сумою конвертації. У таких сценаріях заздалегідь перевіряйте напрям руху коштів у бізнес-процесі.

Субʼєкт платежу

Пара payment_subject_type і payment_subject визначає, до чого відноситься платіж.

Приклади:

• Contragent - покупець або постачальник;
• Expense - стаття витрат;
• Bankbox - банківський рахунок;
• Cashbox - каса;
• Founder - засновник;
• Agency - установа;
• Tax - податок;
• Employee - співробітник.

Для payment_subject використовується обʼєкт з такими полями:

Поле	Призначення
id	ID наявного обʼєкта платежу.
code	Код.
title	Назва або імʼя.
phone	Телефон, якщо обʼєктом є контрагент.
email	Email, якщо обʼєктом є контрагент.
discount_card	Дисконтна картка, якщо обʼєктом є контрагент.
address	Адреса, якщо обʼєктом є контрагент.
group_id	Група, якщо обʼєктом є контрагент.
status_id	Статус.
entity_type	Тип особи або компанії.
bank_id	Банк.
bank_account	Банківський рахунок.
taxnumber	Податковий номер.
remark	Примітка.

Для контрагента найнадійніше передавати id, якщо він уже є в Skynum.

Додатковий субʼєкт платежу

Поле subject_signify використовується для окремих сценаріїв, де потрібно вказати додатковий субʼєкт платежу.

Зокрема, воно використовується з typepayment = expense. Наприклад, витрата може мати статтю витрат як основний обʼєкт, але додатково бути повʼязана з контрагентом.

У subject_signify приймаються такі поля:

Поле	Призначення
id	ID контрагента.
code	Код контрагента.
title	Назва або імʼя контрагента.
phone	Телефон.
email	Email.
discount_card	Дисконтна картка.
address	Адреса.
group_id	Група контрагента.
status_id	Статус контрагента.
entity_type	Тип особи або компанії.
bank_id	Банк.
bank_account	Банківський рахунок.
taxnumber	Податковий номер.
remark	Примітка.

Звʼязок платежу з документом

Щоб привʼязати платіж до документа, використовується binds.

Приклад:

{
  "payment": {
    "typedoc": "cash_in",
    "amount": 1000,
    "typepayment": "settlement_with_clients",
    "binds": [
      {
        "bind_id": "document-id",
        "amount": 1000
      }
    ]
  }
}

bind_id - ID активованого документа, до якого привʼязується платіж. amount - сума, яка розподіляється на цей документ.

Якщо один платіж закриває кілька документів, у binds передають кілька рядків.

Документ у binds має відповідати платежу: дата документа не повинна бути пізнішою за дату платежу, контрагент, філія і валюта мають збігатися, документ має бути активованим, а сума звʼязку має бути більшою за нуль.

порада

Якщо інтеграція отримує оплату разом із замовленням або продажем, заздалегідь визначте, хто створює фінальний звʼязок: документ через оплату в документі, окремий платіж через binds або автоматичне звʼязування.

Автоматичне звʼязування

Поле disable_autobind керує автоматичним звʼязуванням платежу.

• false - автоматичне звʼязування не вимкнене;
• true - інтеграція вимикає автоматичне звʼязування і має передати потрібні звʼязки самостійно.

Якщо для інтеграції критично, який саме документ закриває платіж, передавайте binds явно.

ПДВ у платежі

Поле nds передає суму ПДВ у платежі.

Це поле потрібно використовувати обережно: API фіксує значення в платежі, але остаточне податкове трактування операції залежить від облікової політики компанії та налаштувань ПДВ у Skynum.

Докладніше: ПДВ.

Валюта і конвертація

Для звичайного платежу використовуються:

• currency_id;
• currency_rate;
• amount.

Для конвертацій додатково використовуються:

• converted_currency_id;
• converted_amount.

Якщо компанія веде мультивалютний облік, інтеграція має передавати валюту й курс відповідно до сценарію платежу.

Докладніше: Мультивалютний облік.

Оновлення платежу

PUT /v1/payments/:id оновлює платіж.

Перед оновленням платежу потрібно врахувати його активність і звʼязки з документами.

попередження

Не оновлюйте активний платіж без розуміння наслідків для взаєморозрахунків, каси, банку й звітів. Якщо потрібно змінити облікову операцію, спочатку перевірте, чи можна деактивувати платіж.

Активація платежу

Endpoint:

PUT /v1/payments/:id/activate

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

• збільшити або зменшити залишок каси;
• збільшити або зменшити залишок банківського рахунку;
• закрити борг покупця або постачальника;
• зафіксувати витрату;
• провести податок;
• перенести кошти між касою, банком або валютами.

Деактивація платежу

Endpoint:

PUT /v1/payments/:id/deactivate

Деактивація скасовує фінансовий рух, якщо це дозволено поточним станом обліку.

Деактивація може бути небажаною або неможливою, якщо платіж:

• повʼязаний з активними документами;
• уже бере участь у взаєморозрахунках;
• впливає на закриті періоди;
• створений автоматично іншим процесом;
• повʼязаний з банківською випискою або роздрібною операцією.

Видалення платежу

DELETE /v1/payments/:id видаляє платіж, якщо це дозволено системою.

Для облікових інтеграцій безпечніше не покладатися на видалення як на основний сценарій виправлення. Краще:

1. створювати платіж як чернетку;
2. перевіряти відповідь API;
3. активувати тільки після перевірки;
4. у разі помилки фіксувати її в інтеграції й передавати оператору або відповідальному менеджеру.

Безпечний порядок роботи

Для інтеграцій із платежами рекомендований такий порядок:

1. Отримати довідники кас, банківських рахунків, контрагентів, статей витрат, установ або податків.
2. Визначити typedoc і typepayment.
3. Передати суму, валюту, касу або рахунок.
4. Передати payment_subject_type і payment_subject.
5. Якщо платіж закриває документ, передати binds.
6. Створити платіж як чернетку.
7. Перевірити відповідь API.
8. Активувати платіж.
9. Повторно отримати платіж і перевірити active, суму, валюту й звʼязки.

Чеклист перед запуском

Перед запуском інтеграції з платежами перевірте:

• які typedoc створює інтеграція;
• які typepayment потрібні для бізнес-сценаріїв;
• як визначається каса або банківський рахунок;
• чи передається правильна валюта і курс;
• чи потрібен ПДВ у платежі;
• хто є субʼєктом платежу;
• чи потрібно передавати subject_signify;
• чи потрібно вимикати автоматичне звʼязування;
• як платежі звʼязуються з документами;
• що робити, якщо документ уже оплачений або сума платежу більша за суму документа;
• як інтеграція обробляє повторні запити й помилки активації.

Підсумок

Платежі через API потрібно розглядати як фінансові документи. Для коректного обліку важливо правильно передати typedoc, typepayment, касу або банківський рахунок, суму, валюту, субʼєкта платежу й звʼязки з документами.