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

Протоколи tls 1.0 та 1.1 не підтримуються! Рекомендуємо використовувати tls 1.3

Сервіс доступний для юр. осіб в тарифах “Бізнес Комфорт” та “Бізнес Про” Для ФОП сервіс доступний в будь якому тарифі.

Створення профілю та отримання даних для авторизації

Щоб одержати авторизаційні дані, потрібно підключити додаток «Автоклієнт», як зазначено в інструкції (пункти 1 та 2). Далі натиснути кнопку «Підключити додаток» і вибрати з розкривного списку API.

Ввести назву додатка та IP-адреси (за потреби), ознайомитися з умовами й правилами використання, поставити прапорець і натиснути кнопку «Зберегти».

Після створення додатка API потрібно перейти до налаштувань, натиснувши на . Ознайомитися з умовами використання та натиснути кнопку «Ознайомлений(а)».

У модальному вікні скопіювати token (достатньо натиснути на піктограму ліворуч від слова token).

Натиснувши кнопку «Отримати авторизаційні дані в старому форматі», ви можете одержати окремо ID та token.

Взаємодія з API

Усі запити повинні містити обов’язкові поля в header:

User-Agent – клієнтський додаток;
token – отриманий із налаштувань token;
Content-Type – application/json;charset=cp1251.

Підтримувані кодування utf8 і cp1251. Якщо charset не зазначено, кодування за замовчуванням cp1251.

Отримання балансів і транзакцій за рахунками

Запити надсилаються за допомогою методу GET.

Отримання серверних дат

https://acp.privatbank.ua/api/statements/settings

Приклад відповіді

{

"status": "SUCCESS",

"type": "settings",

"settings": {

"phase": "WRK",

"dates_without_oper_day": // дні без опер. днів

"01.01.2018 00:00:00",

"30.12.2018 00:00:00",

"31.12.2018 00:00:00",

"01.01.2019 00:00:00",

"29.12.2019 00:00:00",

"30.12.2019 00:00:00",

"31.12.2019 00:00:00",

"01.01.2020 00:00:00"

"today": "30.03.2020 00:00:00", // дата поточного опер. дня (проміжна виписка)

"lastday": "29.03.2020 00:00:00", // дата минулого опер. дня (проміжна виписка)

"work_balance": "N", // чи проходять регламент завдання, N – можна робити запити, Y – запити не робити

"server_date_time": "30.03.2020 12:03:51",

"date_final_statement": "28.03.2020 00:00:00" // дата, включно з якої є підсумкова виписка

}

Якщо значення phase відмінне від WRK, то в цей період запити до API можуть повертатися з помилками.

За інтервал дат

https://acp.privatbank.ua/api/statements/balance - для отримання балансів

https://acp.privatbank.ua/api/statements/transactions - для отримання транзакцій

?acc=номер рахунку

&startDate=ДД-ММ-ГГГГ - дата початку (обов’язковий параметр)

&endDate=ДД-ММ-ГГГГ - дата закінчення (необов’язковий параметр)

&followId=id наступної пачки з відповіді (необов’язковий параметр)

&limit=кількість записів у пачці (за замовчуванням 20), максимальне значення - 500, рекомендується використовувати не більше 100

Отримати проміжні дані – з lastday по today

https://acp.privatbank.ua/api/statements/balance(або transactions)/interim

?acc=номерРахунку

&followId=id наступної пачки з відповіді (необов'язковий параметр)

Отримати дані за останній підсумковий день:

https://acp.privatbank.ua/api/statements/balance(или transactions)/final

?acc=номер рахунку

&followId=id наступної пачки з відповіді (необов’язковий параметр)

Якщо номер рахунку не зазначено (немає параметра acc= і значення), дані будуть сформовані за всіма активними рахунками.

Якщо у відповіді параметр exist_next_page: true, значення з next_page_id потрібно підставити в наступний запит у параметр followId для отримання наступної пачки.

Приклад відповіді з балансами

{

"status": "SUCCESS", // ознака успішності відповіді

"type": "balances", // тип відповіді

"exist_next_page": true, // ознака наявності наступної пачки

"next_page_id": "26101050000888", // ідентифікатор наступної пачки (підставляється у followId наступного запиту)

"balances": [ // масив об’єктів із балансами

{

"acc": "UA943052990000026100050001037", // номер рахунку

"currency": "UAH", // валюта

"balanceIn": "0.00", // залишок на рахунку вхідний

"balanceInEq": "0.00", // залишок на рахунку вхідний (екв. у нац. валюті)

"balanceOut": "0.00", // залишок на рахунку вихідний

"balanceOutEq": "0.00", // залишок на рахунку вихідний (екв. у нац. валюті)

"turnoverDebt": "0.00", // оборот, дебет

"turnoverDebtEq": "0.00", // оборот, дебет (екв. у нац. валюті)

"turnoverCred": "0.00", // оборот, кредит

"turnoverCredEq": "0.00", // оборот, кредит (екв. у нац. валюті)

"bgfIBrnm": " ", // бранч, що залучив контрагента

"brnm": "DNH0", // бранч рахунку

"dpd": "09.03.2020 00:00:00", // дата останнього руху за рахунком

"nameACC": "Програмiсти та Ko МСБ-ТЕСТ ТОВ", // найменування рахунку

"state": "l",

"atp": "D",

"flmn": "DN",

"date_open_acc_reg": "28.12.2016 00:00:00",

"date_open_acc_sys": "28.12.2016 00:00:00",

"date_close_acc": "01.01.1900 00:00:00",

"is_final_bal": true

},{...}

]}

Приклад відповіді з транзакціями

{

"status": "SUCCESS", // ознака успішності відповіді

"type": "transactions", // тип відповіді

"exist_next_page": true, // ознака наявності наступної пачки

"next_page_id": "620699370_online", // ідентифікатор наступної пачки (підставляється у followId наступного запиту)

"transactions": [ // масив об’єктів із транзакціями

{

"AUT_MY_CRF": "31451288", // ЄДРПОУ одержувача

"AUT_MY_MFO": "305299", // МФО одержувача

"AUT_MY_ACC": "26184050001514", // рахунок одержувача

"AUT_MY_NAM": "Програмiсти та Ko МСБ-ТЕСТ ТОВ", // назва одержувача

"AUT_MY_MFO_NAME": "АТ КБ \"ПРИВАТБАНК\"", // банк одержувача

"AUT_MY_MFO_CITY": "Київ", // назва міста банку

"AUT_CNTR_CRF": "14360570", // ЄДРПОУ контрагента

"AUT_CNTR_MFO": "305299", // МФО контрагента

"AUT_CNTR_ACC": "70214924104032", // рахунок контрагента

"AUT_CNTR_NAM": "ПРОЦ ВИТР ЗА СТРОК КОШТ СУБ(UAH)", // назва контрагента

"AUT_CNTR_MFO_NAME": "АТ КБ \"ПРИВАТБАНК\"", // назва банку контрагента

"AUT_CNTR_MFO_CITY": "Київ", // назва міста банку

"CCY": "UAH", // валюта

"FL_REAL": "r", // ознака реальності проведення (r,i)

"PR_PR": "r", // стан p - проводиться, t - сторнована, r - проведена, n - забракована

"DOC_TYP": "m", // тип пл. документа

"NUM_DOC": "K0108B1WKX", // номер документа

"DAT_KL": "07.01.2020", // клієнтська дата

"DAT_OD": "07.01.2020", // дата валютування

"OSND": "Нарахування вiдсоткiв згiдно депозитного договору N...", // підстава платежу

"SUM": "0.01", // сума

"SUM_E": "0.01", // сума в національній валюті (грн)

"REF": "DNCHK0108B1WKX", // референс проведення

"REFN": "1", // № з/п всередині проведення

"TIM_P": "02:58", // час проведення

"DATE_TIME_DAT_OD_TIM_P": "07.01.2020 02:58:00",

"ID": "557091731", // ID транзакції

"TRANTYPE": "C", // тип транзакції дебет/кредит (D, C)

"DLR": "J63DNDSM0XHY5", // референс платежу сервісу, через який створювали платіж (payment_pack_ref - у разі створення платежу через АPI «Автоклієнт»)

"TECHNICAL_TRANSACTION_ID": "557091731_online"

}, {...}

]}

Для виконання вимог НБУ, у відповіді можуть бути також додаткові поля, які відносяться до кінцевого платника/отримувача:

"UETR":"b23aeadc-1ab7-4c34-a005-0f005a059948", // ідентифікатор тразакції

"ULTMT":"N", // тип заповненості реквізитів

"PAYER_ULTMT_NCEO":"", // ЄДРПОУ кінцевого платника

"PAYER_ULTMT_DOCUMENT":"", // серія, номер паспорту кінцевого платника

"PAYER_ULTMT_NAME":"", // назва кінцевого платника

"PAYER_ULTMT_COUNTRY_CODE":"", // код країни нерезидента кінцевого платника

"RECIPIENT_ULTMT_NCEO":"", // ЄДРПОУ кінцевого отримувача

"RECIPIENT_ULTMT_DOCUMENT":"", // серія, номер паспорту кінцевого отримувача

"RECIPIENT_ULTMT_NAME":"", // назва кінцевого отримувача

"RECIPIENT_ULTMT_COUNTRY_CODE":"" // код країни нерезидента кінцевого отримувача

Для податкових платежів також додані нові поля для структурованого призначення платежу:

"STRUCT_CODE":”101”, // код виду сплати
"STRUCT_TYPE":”22080000”, // код бюджетної класифікації

"STRUCT_CATEGORY":”Довільний текст” // Інформація про податкове повідомлення (рішення)

Робота в режимі групи ПП

Отримання списку клієнтів, які входять до групи ПП (тільки якщо «Автоклієнт» створено для групи ПП)

GET-запит

https://acp.privatbank.ua/api/account/get-clients-ingroup

Приклад відповіді

{

"clients_in_group": [

"44******05",

"12******71",

"51******88",

]

}

Для роботи з API в режимі групи ПП на всі запити в рядку запиту потрібно додавати параметр ID = {id клієнта в групі}, наприклад statements/balance?id=44****05.

Якщо на запити до API з обліковим записом «Працює в режимі групи» не буде передано ID – буде повернуто помилку 400.

І навпаки, у разі передання ID не в режимі групи також буде повернуто помилку 400.

Отримання курсів валют

https://acp.privatbank.ua/api/proxy/currency/

Отримання історії курсів валют

https://acp.privatbank.ua/api/proxy/currency/history?

startDate=ДД-ММ-ГГГГ&endDate=ДД-ММ-ГГГГ

startDate, endDate – дата початку й закінчення періоду (не більше ніж 15 днів).

Приклад відповіді

{

"cache_info": {

"from_cache": true,

"cache_time": 1526645093874,

"server_time": 1526645134001

"USD": {

"B": {

"date": "18-05-2018 14:00:01",

"rate": "26.0700000",

"rate_delta": "-0.0600000",

"nbuRate": "26.1888140"

"S": {

"date": "18-05-2018 10:04:13",

"rate": "26.3200000",

"rate_delta": "-0.0100000",

"nbuRate": "26.1888140"

}

"EUR": {

"B": {

"date": "18-05-2018 14:00:29",

"rate": "30.7300000",

"rate_delta": "-0.0700000",

"nbuRate": "30.9158950"

"S": {

"date": "18-05-2018 13:45:40",

"rate": "31.3000000",

"rate_delta": "0.0000000",

"nbuRate": "30.9158950"

}

Де:

from_cache – ознака кешування даних;
cache_time – час кешування (в мілісекундах);
server_time – поточний час сервера (в мілісекундах);
B – купівля;
S – продаж;
date – дата курсу;
rate – курс;
rate_delta – зміна курсу;
nbuRate – курс НБУ.

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

З прогнозом: https://acp.privatbank.ua/api/proxy/payment/create_pred

Без прогнозу: https://acp.privatbank.ua/api/proxy/payment/create

BODY

Тіло запиту – це JSON-об’єкт із реквізитами платежу. Усі реквізити типу string.

Обов’язкові реквізити:

document_number – номер документа;
payer_account – рахунок відправника;
recipient_account – рахунок одержувача (або recipient_card для платежу на картку);
recipient_nceo – ЄДРПОУ одержувача;
payment_naming – назва одержувача;
payment_amount – сума платежу;
payment_destination – призначення платежу (від 5 до 420 символів, якщо платіж до податкової, мфо отримувача 899998 то максимальна довжина складає 140 символів).

У випадку, якщо отримувач не має ЄДРПОУ (ФОП віруючий), в полі recipient_nceo вказується 0000000000 та додатково передаються дані паспорту:

recipient_document_number - номер паспорту
recipient_document_series - серія паспорту

Для ID паспорту замість номеру та серії паспорту необхідно передававати наступний параметр:

recipient_document_id_number - ID паспорт

Необов’язкові реквізити (їх може не бути):

document_type – тип документа, за замовчуванням cr;
payment_date – дата списання, за замовчуванням поточна (змінюється за допомогою поля «Дата виконання»);
payment_accept_date – дата зарахування одержувача, за замовчуванням (змінюється за допомогою поля «Дата валютування»);
payment_cb_ref – референс платежу з попереднього Приват24 (якщо імпортований);
copy_from_ref – референс платежу, з якого скопійований;
attach – прикріплені файли;
signer_msg – повідомлення підписанту;
odb_msg – повідомлення операціоністу;
recipient_ifi – МФО банку одержувача;
recipient_ifi_text – назва банку одержувача.
payer_ultmt_nceo - ЄДРПОУ фактичного платника ("^[0-9]{8,10}$")
payer_ultmt_document_series - серія документу фактичного платника ("^[А-Яа-яёЁЇїІіЄєҐґ]{1,2}$")
payer_ultmt_document_number - номер документу фактичного платника ("^[0-9]{6}$")
payer_ultmt_document_id_number - номер id документу фактичного платника ("^[0-9]{9}$")
payer_ultmt_name - назва фактичного платника (символи від 3 до 70)
recipient_ultmt_nceo - ЄДРПОУ фактичного отримувача ("^[0-9]{8,10}$")
recipient_ultmt_document_series - серія документу фактичного отримувача ("^[А-Яа-яёЁЇїІіЄєҐґ]{1,2}$")
recipient_ultmt_document_number - номер документу фактичного отримувача ("^[0-9]{6}$")
recipient_ultmt_document_id_number - номер id документу фактичного отримувача ("^[0-9]{9}$")
recipient_ultmt_name - назва фактичного отримувача (символи від 3 до 70)
struct_code - Код виду сплати (довідник кодів дод.1 до Порядку…) text{1,3}
struct_category - Інформація про податкове повідомлення (рішення) (у разі сплати на єдиний рахунок, відкритий у Казначействі на ім’я ДПС) text{1,140}
struct_type - Тип (у разі сплати за оренду державного майна)Довідник кодів під оренду держмайна підходять 22080000 22080200 22080300 text{1,10}

Приклад тіла запиту

{

"document_number":"autoclient",

"recipient_account":"29001828900110",

"recipient_nceo":"14360570",

"payment_naming":"ПАО, ПАО КБ ПРИВАТБАНК",

"payment_amount":"0.01",

"recipient_ifi":"305299",

"recipient_ifi_text":"ПАТ КБ \"ПРИВАТБАНК\"",

"payment_destination":"test create pmnt to rest API",

"payer_account":"26006055314061",

"payment_ccy":"UAH",

"document_type":"cr",

"payment_date":"04.09.2017",

"payment_accept_date":"04.09.2017"

}

Формат успішної відповіді

Код – 201.

Тіло відповіді

{

"payment_ref": "референс створеного платежу"

"payment_pack_ref": "запакований референс створеного платежу"

}

Формат відповіді з помилкою

Код – 400.

Тіло відповіді

{

"status": "ERROR",

"code": "400",

"message": "invalid document number",

"requestId": "20240223_131617_286f",

"serviceCode": "PMTSRV0112"

}

Коди можливих помилок:

PL0386 – код додатка х не підтримує (належить до параметра consumer);
SW0263 – ви не заповнили референс платежу;
PL0007 – валюти х немає в довіднику валют;
PL0005 – сума платежу повинна бути більше ніж 0,00;
PL0004 – не зазначено номер документа;
PL0026 – призначення платежу зазначено неправильно;
PL0014 – рахунок платника не зазначено або його немає в довіднику рахунків;
PL0020 – рахунок одержувача не зазначено або його немає в довіднику рахунків;
PL0429 – зазначено одночасно картку й рахунок одержувача;
PL0049 – не встановлено курс валют;
PL0344 – клієнтська дата не більше ніж х днів;
PL0029 – валюта рахунку відправника відрізняється від валюти документа;
PL0903 – операція можлива тільки для клієнтських рахунків;
PL0234 – заборонено дебет х;
PL0290 – валюта платежу не повинна бути х;
PL0308 – ЄДРПОУ або ІПН платника зазначено некоректно;
PL0309 – ЄДРПОУ або ІПН одержувача зазначено некоректно;
PL0207 – рахунок х не знайдено;
PL0106 – х закрито/заблоковано;
PL0235 – заборонено кредит х;
PL0256 – гасіть на х;
PL0235 – заборонено кредит х;
PL0311 – заповніть номер картки одержувача;
PL0224 – не знайдено філію х;
KL0014 – не знайдено запис для клієнта х;
PL0046 – валютний платіж на чужий банк повинен бути внутрішнім;
PL0011 – МФО одержувача х немає в довіднику МФО;
PL0022 – найменування рахунку одержувача зазначено неправильно;
PL0023 – ключ рахунку одержувача зазначено неправильно, правильний ключ – х;
KL0015 – неправильний код ЄДРПОУ х;
PL0906 – некоректна довжина рахунку х;
PL0041 – не зазначено номер паспорта;
PL0244 – заборонена кореспонденція СЕП НБУ;
PL0424 – заборонено використання коштів для нецільових платежів.

PMTSRV03002 - за алгоритмом луна це не карта
PMTSRV03006 - не валідний номер електронного паспорту (має бути 9 цифр)
PMTMDL004 - платіж не в тому статусі
PMTMDL016 - для створюваного платежу є дублікат у поточному підприємстві за номером документа
PMTMDL116 - для створюваного платежу є дублікат по хешу, хеш складається з реквізитного складу платежу, в тому числі номера документа.
PMTMDL0016 Вказано одночасно і картку та рахунок одержувача
PMTMDL018 Чи не заповнені або невірно заповнені номер/серія/id паспорта одержувача платежу - віруючого (коли у одержувача немає ЄДРПОУ)
PMTMDL023 - передано невідомий type
PMTMDL025 - сервіс уточнення реквізитів з платежу, що не повернув обов'язкове поле
PMTMDL026 - уточнення реквізитів платежу в невідповідному статусі
PMTMDL034 - Валюта платежу/рахунку не відповідає типу платежу
PMTSRV0000 - помилка при створенні за замовчуванням
PMTSRV0100 - не вистачає обов'язкового параметра при створенні(в message - якого)
PMTSRV0101 - рахунок не належить користувачеві
PMTSRV0110 - неправильна сума
PMTSRV0111 - неправильне призначення
PMTSRV0112 - неправильний номер документа
PMTSRV0113 - неправильний рахунок отримувача
PMTSRV0114 - неправильний код одержувача
PMTSRV0115 - неправильне найменування одержувача
PMTSRV0116 - неправильний код банку отримувача
PMTSRV0117 - неправильний рахунок відправника
PMTSRV0118 - неправильна дата валютування
PMTSRV0119 - неправильна дата виконання
PMTSRV0123 - не валідне значення валюти платежу чи валюта платежу не збігається з валютою рахунку
PMTSRV02007 - api не може обробити поле
PMTSRV02009 - невалідне поле повідомлення підписанту
PMTSRV0103 - помилка при вказівці типу платежу, поле "document_type"
PMTSRV03001 - помилка у вказівці картки одержувача, поле "recipient_card"
PMTSRV03005 - невалідне поле коментаря співробітника банку
PMTSRV03003 – номер паспорта одержувача не пройшов валідацію
PMTSRV03004 - помилка у серії паспорта одержувача
PMTMDL038 - помилка створення податкового платежу, невірно заповнено одне з полів: struct_code, struct_category, struct_type
PMTSRV1111 - поле struct_category має бути не менш ніж 1 символ, та не перевищувати 140 символів

Опрацювання помилок

У разі виникнення помилки сервер повертає JSON-об’єкт виду:

{

"status": "ERROR",

"code": "400",

"message": "invalid document number",

"requestId": "20240223_131617_286f",

"serviceCode": "PMTSRV0112"

}

Коди HTTP-відповідей у разі виникнення помилок:

401 – некоректні облікові дані для доступу (token автоклієнта передано неправильно);
400 – некоректний формат запиту або немає одного чи декількох обов’язкових заголовків;
403 – якщо обліковий запис відключено через налаштування додатка «Автоклієнт» у «Приват24 для бізнесу» (див. інструкцію);
500, 502 – внутрішня помилка сервера;
503, 504 – у разі тимчасової недоступності сервісу.

Електронний документообіг (в т.ч. Інвойсинг)

«Приват24 для бізнесу» (меню «Каталог послуг» – «Електронний документообіг») або docs.pb.ua

Усі запити надсилаються на https://acp.privatbank.ua.

Журнал документів

content-type: application/json

POST-запит

/api/proxy/edoc/journal/inbox // Вхідні

/api/proxy/edoc/journal/outbox // Вихідні

/api/proxy/edoc/journal/in-process // В роботі

/api/proxy/edoc/journal/all // Всі (вхідні + вихідні + в роботі)

/api/proxy/edoc/journal/to-pay // До сплати

Параметри запиту з прикладами значень

Обов’язкові:

"dateBegin": "2016-11-30" // початкова дата фільтрації видачі
"dateEnd": "2019-03-29" // кінцева дата фільтрації видачі (включно)

Необов’язкові (в дужках зазначено номер примітки):

"dateSource": "document" // фільтрація видачі за датою, зазначеною в документі (1)
"okpo": ["34554355"] // ЄДРПОУ відправника/одержувача (2)
"relatedOkpo": "31435622" // ЄДРПОУ одержувача
"limit": "50 // кількість записів у видачі (3)
"offset": "20" // зміщення щодо першого запису у видачі
"docType" :"["2657"] // код типу документа
"status": ["7"] // код статусу документа
"sortBy": "amount" // критерій сортування видачі (4)
"orderBy": "asc" // порядок сортування видачі: asc – прямий, desc – зворотний (5)
"unreadBy": "user" // видача тільки непереглянутих повідомлень
"stringFilter": "%5B%7B%22searchBy%22:%22everything%22,%22key%22:%22%D1%84%D0%B0 %D0%BA%D1%82%D1%83%D1%80%D0%B0%22%7D%5D" // фільтрація видачі за рядковим виразом (6)
"docSumFrom" : "120.00" // фільтрація: сума за документом не менше ніж
"docSumTo": "800" // фільтрація: сума за документом не більше ніж

Примітки

Якщо не передано параметр dateSource, для фільтрації видачі використовується або дата створення (in-process), або дата отримання (inbox), або дата надсилання (outbox) документа.
Якщо не передано параметр okpo, відбір здійснюється за всіма доступними для клієнта ЄДРПОУ.
Якщо не передано параметр limit, за замовчуванням використовується значення 5000.
Параметр sortBy приймає одне зі значень:

doc_id (внутрішній ідентифікатор документа, використовується за замовчуванням);
type (код типу);
status (код статусу);
sending_time (дата надсилання);
receipt_time (дата отримання);
last_modify_time (дата останньої зміни);
amount (сума документа);
doc_date (дата документа, зазначена в його вмісті);
create_time (дата створення/імпорту документа в систему);
sender_okpo (ЄДРПОУ відправника);
recipient_okpo (ЄДРПОУ одержувача).

Якщо не передано параметр orderBy, за замовчуванням використовується зворотний порядок сортування видачі (від більшого до меншого).
Параметр stringFilter дає змогу фільтрувати видачу за деякими ознаками документа:

company (контрагент: найменування + ЄДРПОУ) // ПП «Ромашка», 12345678;
docName (назва файлу + назва типу документа + номер документа) // фактура, doc.xml;
docStatus (статус документа) // підписано, надіслано;
docSum (сума документа) // 565,20;
everything (фільтрація за всіма переліченими вище ознаками).

Значення параметра є масивом необмеженої кількості валідних JSON-рядків формату {"searchBy": "ознака", "key": "текст"}. Рядок повинен бути закодований за допомогою алгоритму URL-encoding. Кожен пошуковий ключ повинен складатися мінімум із трьох символів. Ознаки та ключі не чутливі до регістру.

Приклад тіла запиту

{

"dateBegin": "2019-01-15",

"dateEnd": "2019-04-25",

"limit": "10",

"okpo": [

"31451288",

"34554355"

"dateSource": "document",

"orderBy": "asc",

"sortBy": "doc_date",

"docType": [

"2800",

"2756"

"docSumFrom": "512.30",

"docSumTo": "1050.00",

"stringFilter":"%5B%7B%22searchBy%22:%22everything%22,%22key%22:%22%D1%84%D0%B0%D0%BA%D1%82%D1%83%D1%80%D0%B0%22%7D,%7B%22searchBy%22:%22company%22,%22key%22:%22%D1%80%D0%BE%D0%BC%D0%B0%D1%88%D0%BA%D0%B0%22%7D%5D"

}

Формат успішної відповіді

Статус – 200 ОК.

Приклад тіла відповіді

{

"documents": [ // масив об’єктів із документами

{

"idStr": null,

"CREATE_DATE": "2024-06-20 15:59:24", // дата створення

"DOC_DATE": "2024-06-20", // дата, у документі

"RECEIPT_DATE": "2019-01-29 16:12:03", // дата отримання

"SEND_DATE": “2019-01-29 16:12:03”, // дата надсилання

"TAX_HDATETIME": null, // дата з податкової квитанції

"TAX_HNUMREG": null, // номер податкової квитанції

"AMOUNT": 0.00, // сума

"STATUS": 3, // код статусу

"STATUS_NAME": "READY_TO_WORK", // назва статусу

"OKPO_SENDER": "00000000", // ЄДРПОУ відправника

"OKPO_RECIPIENT": "14360570", // ЄДРПОУ одержувача

"DOC_NUMBER": "107", // номер документа

"ORIGINAL_DOC_NAME": "invoice.xml", //назва файлу документа під час створення

"DOC_TYPE": 2654, // код типу документа

"OKPO_RECIPIENT_NAME": "АТ КБ \"ПРИВАТБАНК\"", // контрагент-одержувач

"OKPO_SENDER_NAME": "ТОВ TEST_TEST", // контрагент-відправник

"ID": 1332185843, // системний ідентифікатор документа

"LAST_MODIFY_TIME": "2024-06-20 15:59:24", // дата і час останньої зміни

"DOC_NAME": "invoice.xml", // назва документа

"IS_EDITED": false, // документ редагувався після створення/завантаження

"NEED_TO_EDIT": false,

"IS_RENDERED_TO_PDF": false,

"CREATOR": "USER", // внутрішній тип створювача документа

"ADDITION_STATUS": null, // додатковий статус

"TAX_RESULT_STATUS": "UNKNOWN", // статус надсилання в податкову

"ID_OF_BASE_DOC": null, // ідентифікатор базового документа

"DOC_ADDITIONAL_DATA": "{\"vat\": \"0.0\"}", // додаткові системні дані

"TIN_SENDER": null,

"TIN_RECIPIENT": null,

"VAT": "0.0", // сума ПДВ документа

"UNREAD_SENDER": 0, // не переглянуто відправником (1 – так, 0 – ні)

"UNREAD_RECIPIENT": 0, // не переглянуто одержувачем (1 – так, 0 – ні)

"PAYMENT_REFERENCE": null,

"COMMENT": null, // коментар отримувача при відмові

"TAGS": null,

"TAXES": null,

"UNREAD_DISCUSSION_SENDER": 0,

"UNREAD_DISCUSSION_RECIPIENT": 0

}

"total": 1, // загальна кількість доступних документів за запитом

"offset": 0, // зміщення щодо першого документа

"limit": 10 // максимальна кількість записів у видачі

"sortedBy": "DOC_DATE" // ознака, за якою відсортовано видачу

}

Опис статусів документів, назва статусу, у дужках - код статусу:

READY_TO_WORK(3),//Збережено

SIGNED_BY_SENDER(4), //підписано відправником

SENDING_TO_TAX(6), //відправляється в податкову

SENT_TO_TAX(7), //відправлений в податкову

REGISTERED_IN_TAX(8), //отриманий в податковій

REJECTED_IN_TAX(9), //відхилено податковою

RECEIVED_IN_TAX(10), //прийнятий податковою

REJECTED_BY_RECIPIENT(11), //відхилено контрагентом

SIGNED_BY_RECIPIENT(12), //підписаний контрагентом

RECIPIENT_PREVIEW(14), //відправлений без підпису

APPROVED_BY_RECIPIENT(15), //затверджено (без підпису)

DELETED(16), //видалений (не повертається в журнал)

PREPARED_FOR_SENDING_TO_TAX(17), //Підготовлений до відправки в податкову UPLOADED_AS_ENCRYPTED(18), //Документ зашифрований DECRYPTED_TAX_TECHNICAL_DOC(19); //Розшифрований (є квитанція) PAYMENT_WAS_CREATED - Створений платіж (додатковий статус)

PAYMENT_WAS_IGNORED- Не платити (додатковий статус)

WAITING_FOR_DECRYPTION - Очікує розшифровки (додатковий статус)

DECRYPTED - Розшифрований (додатковий статус)

(22) підписаний не відправлений - не реалізовано

PAYMENT_WAS_BLOCKED - Повернено платіж (додатковий статус)

PAYMENT_WAS_PAYED - Оплачено платіж (додатковий статус)

PAYMENT_WAS_DELETED - видалено платіж (додатковий статус)

30 статус підписано (Кінцевий покупець)

Формат відповіді з помилкою

Можливі коди відповіді:

400 – некоректний формат або параметри запиту;
401 – запит від неавторизованого користувача;
403 – запит недоступного цьому користувачеві ресурсу;
404 – запитуваний ресурс не існує;
415 – непідтримуваний тип запиту;
500, 502 – внутрішня помилка сервера;
503, 504 – тимчасова недоступність сервера.

Приклад тіла відповіді з помилкою

{

"status": "ERROR", // статус відповіді

"code": "VE005", // код помилки

"message": "Помилкові параметри: asac", // опис помилки

"requestId": "ae16785e-3223-4e6b-8c21-259b7dc768ec", // ідентифікатор запиту

"createTime": "2019-04-15 17:31:34.275", // дата та час помилки

"details": { // додаткова інформація

"descr": "Incorrect request parameters: {0}", // шаблон повідомлення про помилку

"arguments": [ // список аргументів у повідомленні про помилку

"asac"

"additionalInfo": "'OrderBy' accepts only 'decs' or 'acs' values ignore case" // додаткова інформація (необов’язково)

}

Примітка

У разі виникнення запитань щодо опрацювання помилок сервісом ЕДО важливо зазначати унікальний ідентифікатор запиту. Це допоможе розв’язати проблему якнайшвидше.

Завантаження документів XML (без ЕЦП) (в т.ч. це ІНВОЙСИНГ)

content-type: multipart/form-data

POST-запит

/api/proxy/edoc/loader/upload

Параметри:

file – multipartFile;
okpo – ЄДРПОУ відправника;
tempLinkForDays – час життя тимчасового посилання на документ, який буде повернуто у відповідь на успішний запит (необов’язково; за замовчуванням 7).

Приклад успішної відповіді

{

"STATUS":"SUCCESS", статус успішно/помилка

"id":"0000000000", ID створеного документа

“TEMP_LINK”: “тимчасове посилання на документ (якщо параметр tempLinkForDays був переданий)”

}

Приклад відповіді з помилкою
{

"status":"ERROR", статус успішно/помилка

"code":"VE011", код помилки

"message":"Дублікат документа 00000 у стадії \"Підписаний відправником\" вже існує", опис помилки

"requestId":"01022023_014515_f79", ID запиту

"createTime":"2023-02-01 13:45:15.086", дата створення запиту

"details":{"descr":"Document duplicate with id {0} in stage {1} already exist", деталі помилки

"arguments":[00000,"SIGNED_BY_SENDER"]}, причина помилки

}

Отримати приклад XML-файлу та структури документа можна створивши документ у вебверсії «Приват24 для бізнесу» (меню «Каталог послуг» – «Електронний документообіг»). Після створення, заповнення та збереження документа його потрібно вивантажити у форматі XML. Одержаний файл і буде мати необхідну структуру. Детальніше про електронний документообіг – за посиланням.

Завантаження документів XML з одночасним надсиланням контрагентові з ЕЦП (в т.ч. це ІНВОЙСИНГ)

content-type: multipart/form-data

POST-запит
Основний url:
https://docs.24.privatbank.ua/loader/v2/upload-signed-xml

Додатковий url, якщо основний не працює: https://acp.privatbank.ua/api/proxy/edoc/loader/upload-signed-xml

Параметри:

file – multipartFile;
okpo – ЄДРПОУ відправника;
tempLinkForDays – час життя тимчасового посилання на документ, який буде повернуто у відповідь на успішний запит (за замовчуванням 7; якщо тимчасове посилання не потрібне, передавати 0).

Приклад відповіді

{

“id”: ID створеного й надісланого документа

“TEMP_LINK”: “тимчасове посилання на документ (якщо під час надсилання не було передано 0)”

}

Завантаження документів PDF (без ЕЦП)

content-type: multipart/form-data

POST-запит

/api/proxy/edoc/loader/upload-pdf

Параметри:

file – multipartFile;
okpo – ЄДРПОУ відправника;
recipientOkpo – ЄДРПОУ одержувача;
recipientName – назва одержувача (необов’язково);
documentDate – дата документа (необов’язково);
amount – сума (необов’язково);
documentNum – номер документа (необов’язково);
tempLinkForDays – час життя тимчасового посилання на документ, який буде повернуто у відповідь на успішний запит (необов’язково; за замовчуванням 7).

Приклад успішної відповіді

{

"STATUS":"SUCCESS", статус успішно/помилка

"id":"0000000000", ID створеного документа

“TEMP_LINK”: “тимчасове посилання на документ (якщо параметр tempLinkForDays був переданий)”

}

Приклад відповіді з помилкою
{

"status":"ERROR", статус успішно/помилка

"code":"VE011", код помилки

"message":"Дублікат документа 00000 у стадії \"Підписаний відправником\" вже існує", опис помилки

"requestId":"01022023_014515_f79", ID запиту

"createTime":"2023-02-01 13:45:15.086", дата створення запиту

"details":{"descr":"Document duplicate with id {0} in stage {1} already exist", деталі помилки

"arguments":[00000,"SIGNED_BY_SENDER"]}, причина помилки

}

Завантаження документів PDF до Base64 (без ЕЦП)

content-type: application/x-www-form-urlencoded

POST-запит

/api/proxy/edoc/loader/upload-pdf-b64

Параметри:

uploadedFileB64 – PDF-документ у Base64;
uploadedFileName – назва файлу документа з розширенням .pdf;
okpo – ЄДРПОУ відправника;
recipientOkpo – ЄДРПОУ одержувача;
recipientName – назва одержувача (необов’язково);
documentDate – дата документа (необов’язково);
amount – сума (необов’язково);
documentNum – номер документа (необов’язково);
tempLinkForDays – час життя тимчасового посилання на документ, який буде повернуто у відповідь на успішний запит (необов’язково; за замовчуванням 7).

Приклад успішної відповіді

{

"STATUS":"SUCCESS", статус успішно/помилка

"id":"0000000000", ID створеного документа

“TEMP_LINK”: “тимчасове посилання на документ (якщо параметр tempLinkForDays був переданий)”

}

Приклад відповіді з помилкою
{

"status":"ERROR", статус успішно/помилка

"code":"VE011", код помилки

"message":"Дублікат документа 00000 у стадії \"Підписаний відправником\" вже існує", опис помилки

"requestId":"01022023_014515_f79", ID запиту

"createTime":"2023-02-01 13:45:15.086", дата створення запиту

"details":{"descr":"Document duplicate with id {0} in stage {1} already exist", деталі помилки

"arguments":[00000,"SIGNED_BY_SENDER"]}, причина помилки

}

content-type: application/x-www-form-urlencoded

POST-запит

/api/proxy/edoc/loader/upload-signed-b64

Параметри:

file – підписаний документ у Base64;
okpo – ЄДРПОУ відправника;
id – ідентифікатор документа, до якого треба додати підпис;
tempLinkForDays – час життя тимчасового посилання на документ, який буде повернуто у відповідь на успішний запит (необов’язково; за замовчуванням 7).

Приклад успішної відповіді

{

"STATUS":"SUCCESS", статус успішно/помилка

"id":"0000000000", ID створеного документа

“TEMP_LINK”: “тимчасове посилання на документ (якщо параметр tempLinkForDays був переданий)”

}

Приклад відповіді з помилкою
{

"status":"ERROR", статус успішно/помилка

"code":"VE011", код помилки

"message":"Дублікат документа 00000 у стадії \"Підписаний відправником\" вже існує", опис помилки

"requestId":"01022023_014515_f79", ID запиту

"createTime":"2023-02-01 13:45:15.086", дата створення запиту

"details":{"descr":"Document duplicate with id {0} in stage {1} already exist", деталі помилки

"arguments":[00000,"SIGNED_BY_SENDER"]}, причина помилки

}

Надсилання контрагентові завантаженого непідписаного документа (в розробці)

GET-запит
/proxy/edoc/journal/send-for-preview/{id}?okpo=okpo

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ поточного контрагента.

Приклад успішної відповіді
{
"STATUS":"SUCCESS"
}

Створення платежу на основі рахунка-фактури

POST-запит

/api/proxy/edoc/create-payment-from-invoice/{id}?okpo=okpo&payerAccount=payerAccount

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ поточного контрагента;
payerAccount – рахунок платника.

Приклад успішної відповіді

{

STATUS: SUCCESS

}

Видалення документа

GET-запит

/api/proxy/edoc/journal/delete/ID?okpo=okpo

Параметри:

ID – ідентифікатор документа для видалення;
okpo – ЄДРПОУ організації.

Отримання XML-документа (application/octet-stream)

GET-запит

/api/proxy/edoc/journal/get-xml-document/ID?okpo=okpo

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ організації.

Отримання Base64-документа (для підписання) (application/json)

GET-запит

/api/proxy/edoc/journal/get-base64/ID?okpo=okpo

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ організації.

Відповідь

{

fileName: ім’я файлу

originalDoc: документ у base64

}

Отримання PDF-документа (application/octet-stream)

GET-запит

/api/proxy/edoc/journal/get-pdf-document/ID?okpo=okpo

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ організації.

Отримання інформації щодо ЕЦП на документі

GET-запит

/api/proxy/edoc/journal/sign-info/ID?okpo=okpo

Параметри:

ID – ідентифікатор документа;
okpo – ЄДРПОУ організації.

Отримання документа з ЕЦП (використовується для XML-документів) у форматі .p7s

GET-запит

/proxy/edoc/journal/get-p7s/ID?okpo=okpo

Параметри

ID – ідентифікатор документа;
okpo – ЄДРПОУ організації.

6. Електронна звітність

«Приват24 для бізнесу» (меню «Каталог послуг» – «Електронна звітність»)

Завантаження (upload) документів

content-type: multipart/form-data

POST-запит

/api/proxy/eo/documents/create

Параметри:

file – multipart/form-data (XML-файл за стандартами ДФС, з назвою, відповідним змістом документа (наприклад 09060031435622J0500105100000000120320190906.XML) або ZIP-архів, якщо файлів декілька (ZIP-архів повинен відповідати імені основного файлу));
okpo – ЄДРПОУ;
duplicate – remove/error*.

Завантаження (upload) документів (у форматі Base64)

content-type: application/x-www-form-urlencoded

POST-запит

/api/proxy/eo/documents/create-b64

Параметри:

uploadedFileB64 – XML-файл за стандартами ДФС, з назвою, відповідним змістом документа (наприклад 09060031435622J0500105100000000120320190906.XML) або ZIP-архів, якщо файлів декілька (ZIP-архів повинен відповідати імені основного файлу);
uploadedFileName – назва файлу;
okpo – ЄДРПОУ;
duplicate – remove/error*.

* duplicate – визначає поведінку ЕО під час спроби створити документ з ідентифікатором у зовнішній системі, з яким в ЕО раніше вже був створений інший документ.

Прийняті значення:

remove – раніше створені документи будуть видалені;
error – буде повернуто помилку (значення за замовчуванням).

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

Успішна відповідь

{

“result”: “success”,

“documents”: [

{

"id": "{ідентифікатор документа в Зовнішній системі}",

“result”: “success”

} ]

}

Відповідь із помилкою

{

“result”: “error”,

"error_message": “{текст помилки}"

{

7. Зарплатний проєкт

«Приват24 для бізнесу» (меню «Каталог послуг» – «Зарплатні та інші виплати»)

Сервіс працює лише зі співробітниками. Для початку роботи рекомендовано отримати перелік співробітників у зарплатному проекті та зберегти їх. При оновленні даних по співробітникам у зарплатному проекті (додано нового співробітника, оновились дані по поточному та ін.) необхідно відправити запит на отримання списку одержувачів та оновити дані.
Для додавання співробітників можна відправити запит на створення відомості, зберегти отриманий референс і додавати необхідних співробітників у створену відомість (вказавши відповідний референс відомості). Також можна отримати перелік вже існуючих відомостей і додавати співробітників у вже існуючу відомість, також вказавши відповідний референс відомості.
Після успішної роботи з додавання співробітників можна відправити відомість на перевірку, або зробити це у Приват24 для бізнесу. Підписати та відправити відомість можна лише у Приват24 для бізнесу.

Робота з доступними групами

Групи – аналог зарплатних проєктів. У межах однієї юридичної особи не може бути більше ніж одна група одного типу.

Отримання списку доступних груп

GET

/api/pay/mp/list-groups

JSON

[

{

“type”: “SALARY”,

“name”: “ім’я проекта”,

“rko”: 0.05

...

]

Type – це тип групи, що може бути одним із таких, але не виключно (не можна припускати, що тільки ці та жодні інші):

MASSPAYMENTS – проєкт типу X;
STUDENT – проєкт типу S;
HESED – проєкт типу H;
SALARY – інші зарплатні проєкти.

Поле rko містить довідковий % комісії з вибраної групи.

Список одержувачів у групі

GET

/api/pay/mp/list-receivers?group=<код групи>&page=0&page-size=100[&filter=<пошукова строка>]

JSON

[

{

“id”: “id-отримувача”,

“pan”: “номер картки/рахунку”,

“fio”:[“прізвище”,”ім’я”,”по-батькові”]

“inn”: “іпн отримувача”,

“group”: “код групи”,

[“tabn”: “табельный номер”]

...

]

Код групи – один із вищезазначених або код ALL (для отримання всіх доступних одержувачів, у будь-яких групах).

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

Атрибут tabn, опціональний загалом, але обов’язковий для груп SALARY і STUDENT.

Атрибут pan надходить у формі маски: “DDDD **** **** DDDD”.

Рекомендований page-size = 100, з підвантаженням, доки список не буде порожнім.

Додавання нового співробітника до групи SALARY/STUDENT

Функції безпосереднього додавання в моделі немає. Додавання поєднане з оновленням, тому update-receiver або додає нового одержувача, або змінює одержувача на наявного табельного (відповідно до логіки управління зарахуванням, якої документ не торкається).

POST

/api/pay/mp/update-receiver

REQ

JSON

{

“pan”: “номер картки/рахунку”,

“group”: “код групи”,

“tabn”: “табельный номер”,

[“inn”: “іпн отримувача”,]

[“fio”:[“прізвище”,”ім’я”,”по-батькові”]]

}

RESP

JSON

{

"status" : "<статус операції УЗ>",

["id" : "<id отримувача>"]

}

Для створення одержувача обов’язковими параметрами є:

група;
табельний номер;
номер картки.

Якщо картка не ПриватБанку, то ІПН та П. І. Б. також стають обов’язковими.

Робота з відомостями

Список відомостей

GET

/api/pay/apay24/packets/list?[status=<filter-status>]&page=0&page-size=100[&from=<початок періоду>&to=<кінець періоду виключно>]

JSON

[

{

“reference”: “референс відомості”,

“system”: “тип відомості”,

“createdAt”: “дата створення”,

“finishedAt”: “дата обробки”,

“status”: “стан відомості”,

“substatus”: “розширений стан відомості”,

“packetName”: “назва відомості”,

“errText”: “текст помилки пов’язаний відомістю”,

“recordCount”: <10, кількість записів>,

“recordAmount”: <10.33, повна сума відомості>,

“revision”: <123, ревізія>

...

]

Де використовуються такі параметри:

filter-status – повертати тільки відомості в зазначених статусах:

V – зберігання – пакети, які ще не затверджено, але дозволено редагувати;
A – на підпис – пакети, які може підписати клієнт;
F – опрацьовані пакети;
R – забраковані пакети;

from,to – пошуковий період із датою у форматі “yyyy-MM-dd”;

період обов'язковий для фільтрів F, R;
період обов'язковий, якщо статуси не зазначено;
період не впливає на інші статуси (наприклад: якщо зазначено статус A, то будуть повернуті всі «На підпис» незалежно від зазначеного періоду;

максимальний розмір сторінки – 100.

У структурі відповіді потрібно звернути увагу на такі поля:

system – підсистема, яка керує відомостями. Наразі їх дві:

reqpay – блок масових виплат, група MASSPAYMENTS;
maspay – зарплатний блок, група SALARY/STUDENT;

status/substatus – основний і додатковий статус відомостей, див. статуси пакетів;
revision – монотонно зростальний внутрішній лічильник модифікацій.

У кожної підсистеми своє API, яке несумісне з іншими, тому потрібно враховувати систему пакета, перш ніж використовувати референс в інших запитах.

Статуси пакетів

Система передбачає такі статуси:

Статус	Підстатус	Коментар
N – створена		Пакет створено, дозволено редагування
W – перевірена		Пакет пройшов успішну перевірку. Його можна затвердити або відізвати на редагування
S – затверджена		Пакет затверджено й може бути підписано або видалено
SB – підписана бухгалтером		Пакет очікує на підпис директора
SD – підписана директором		Пакет очікує на підпис бухгалтера
S$ – повністю підписана		Пакет отримав всі необхідні підписи й може бути надісланий у банк
X – надіслана		Пакет надіслано в банк на опрацювання
P	V	Пакет на перевірці (N → W, N → N)
P		Див. вище
P	I	Пакет опрацьовує імпорт «сирих» файлів (N → N)
F	F	Пакет опрацьовано без помилок
F		Див. вище
F	R	Пакет опрацьовано з помилками
R		Пакет забраковано
D		Пакет видалено

Заголовок пакета maspay

GET

/api/pay/maspay/<референс пакета>/header

JSON

{

“reference”: “референс відомості”,

“createdAt”: “дата створення”,

“finishedAt”: “дата обробки”,

“group”: “код групи”,

“status”: “стан відомості”,

“substatus”: “розширений стан відомості”,

“packetName”: “назва відомості”,

“errText”: “текст помилки пов’язаний відомістю”,

“recordCount”: <10, кількість записів>,

“recordAmount”: <10.33, повна сума відомості>,

“revision”: <123, ревізія>

}

Вміст пакета maspay

GET

/api/pay/maspay/<референс пакета>/content?page=0&page-size=100

JSON

[

{

“ref”:”<референс запису>”,

“fio”:”ПІБ отримувача”,

“inn”:”ІПН отримувача”,

“cardNumber”:”маскований номер”,

“comment”:”призначення виплати”,

“amount”:<сума виплати>,

“status”: “<статус запису>”,

“errorCode”:”<код помилки>”,

“tabNo”: “табельний номер”

...

]

Де:

ref – референс для роботи із записом;
status – статус валідації запису;
errorCode – код помилки, у разі, якщо статус запису «Помилка».

Статуси записів maspay

Статус	Коментар
N	Запис ще не перевірявся
N$	У записі є помилка, яку можна виправити у вебверсії «Приват24 для бізнесу» (наприклад 0 сума)
R	Успішно перевірено
M	Успішно сплачено
E	Забраковано
*	Усе інше можна вважати помилками, на які неможливо вплинути

Додавання отримувача у відомість

POST

/api/pay/maspay/<референс пакета>/add

REQ

JSON

{

“receiver”: “<id отримувача>”

“comment”:”призначення виплати”,

“amount”:<сума виплати>

}

RESP

JSON

{

“ref”: “<реф. нового запису>”

}

Де:

receiver – ID отримувача, отриманий при запиті: Список одержувачів у групі, згідно з групою з управління зарахуванням;
amount – сума має бути > 0;
статус відомості має бути:

N – допускає додавання одержувачів;
W – буде автоматично переведено в N;
інше maspay:L_UNABLE_TO_COMPLETE_OPERATION.

Можливі помилки:

maspay:L_PACKET_OVERFLOW у разі перевищення розміру відомості;

mp:* можливі помилки від УЗ.

Видалення отримувача з відомості

POST

/api/pay/maspay/<референс пакета>/remove

REQ

JSON

{

“ref”: “<референс запису>”

}

RESP

JSON

{

}

Де:

Статус відомості має бути:

N – дозволяє видалення одержувачів;
W – буде автоматично переведено в N.

Надсилання відомості maspay на перевірку

POST

/api/pay/maspay/<референс пакета>/validate

RESP

JSON

див. maspay//header

На перевірку надсилаються пакети в статусі N. Для статусу W запит ігнорується, інше – помилка. Підтвердженням запуску перевірки є status='P' відповіді.

Створення нової відомості maspay

POST

/api/pay/maspay/create

REQ

JSON

{

“group”: “SALARY|STUDENT”,

“salary”: true|false,

[“packetName”: “заголовок відомості”]

}

RESP

JSON

див. maspay//header

Де:

group – дозволяє вибрати, якщо у клієнта > 1 проєкту;
salary – ознака цільова/нецільова.

Загальні помилки системи maspay

Будь-який запит до maspay може викликати такі помилки:

maspay:L_ENTITY_NOT_EXISTS – у разі, якщо такий пакет не існує в системі;
maspay:L_ACCESS_DENIED – якщо зазначено пакет іншої організації;
maspay:V_BAD_PARAM – якщо є помилки в параметрах запиту із зазначенням помилкового параметра;
maspay:L_UNABLE_TO_COMPLETE_OPERATION – за цих умов виконати запит неможливо (зазвичай невідповідність статусу пакета запитуваної операції);
maspay:L_UNABLE_TO_START_VALIDATION – логічно ідентичний L_UNABLE_TO_COMPLETE_OPERATION тільки для запуску перевірки.

Приклад об’єкта, що описує помилку

{

"status": "err",

"error": {

"system": "isa",

"code": "V_BAD_PARAM",

"args": [

"from"

"ref": "39278f1a-cdec-496d-947d-f70dcb84bbd9"

}

8. Розрахункові листи

Отримання журналу зарплатних проєктів

GET /api/paysheets/journal

Відповідь:

content-type: application/json;charset=UTF-8

[

{

"uploadTime": "2021-05-20T00:00:00.000",

"project": {

"reference": "12A08000132",

"name": "TEST TEST MCB_TEST"

"reportYm": "202103",

"fileType": "PAYSHEET",

"status": "UPLOADED"

{....},

...

]

Завантаження довідника та розрахункових листів

POST /api/paysheets/upload-file?projectReference=12A08000132&yearmonth=202106

content-type: multipart/form-data

------WebKitFormBoundaryTdpa0qYehKK0M0nw

Content-Disposition: form-data; name="paysheet"; filename="EMPLOYEES_PAY_20160901_12A08000132.xls"

Content-Type: application/vnd.ms-excel

------WebKitFormBoundaryTdpa0qYehKK0M0nw

Content-Disposition: form-data; name="catalog"; filename="SPRAVOCHNIK_20160901_12A08000132.xls"

Content-Type: application/vnd.ms-excel

Якщо передаються DBF-файли, тоді XLS потрібно змінити на DBF

Успішна відповідь:

{

“status”:”success”

}

Збереження завантажених довідників і розрахункових листів на SFTP. Потрібно викликати відразу після upload-file (у разі успішного завантаження файлів)

POST /api/paysheets/save-files

Успішна відповідь:

{

“status”:”success”

}

Помилки:

HTTP status code: 40x – помилка в клієнтських даних;

HTTP status code: 50x – внутрішня помилка/виключення.

{

"status": "ERROR", // ознака помилки

"code": "400", // HTTP-статус (дублюється із заголовка)

"message": "У файлі 'Відомість' зазначено неправильні табельні номери співробітників. Перевірте табельні номери в меню Виплати, вкладка 'Список отримувачів'", // повідомлення про помилку

"serviceCode": "TABNUM_NOT_PROJECT" // код помилки сервісу

}

Можливі коди помилок:

INVALID_CODE_PAGE Не вдалося визначити кодування DBF-файлу. Збережіть цей файл у кодуванні Windows-1251 або DOS-866.

INVALID_DBF_FIELD_TYPE У файлі на імпорт використовується недопустимий тип поля. Будь ласка, перевірте файл на коректність і повторіть імпорт.

VALID_DUBLICATED_ATTR_ID У файлі \"${0}\" в полі ATTR_ID дублюються дані: ${1}".

P24_PAYSHEET_DBF_WRITE Виникла помилка перетворення вхідного DBF у вихідний.

P24_PAYSHEET_VALID_BIG_FILE Файл \"${0}\" перевищує допустимий розмір ${1} Мб! Для зменшення розміру файлу видаліть рядок із порожніми полями 'Znach1'.

INVALID_FILE_TYPE Структура файлу не відповідає розширенню! Спробуйте додати файл із правильною структурою у форматі *.dbf або *.xls, *.xlsx.

PAYSHEET_VALID_FIELD_TOO_LONG Помилка у файлі \"${0}\": перевищено допустиму довжину поля ${1}. Фактична – ${2}. Допустима – ${3}.

PAYSHEET_JOURNAL_REQUEST_ERR Помилка отримання журналу розрахункових листів: ${0}.

P24_PAYSHEET_JOURNAL_ERR Помилка формування журналу розрахункових листів: ${0}.

LOCAL_P24_PAYSHEET_FTP Виникла помилка під час роботи з FTP-сервером: ${0}.

LOCAL_P24_PAYSHEET_FTP_UPLOAD Виникла помилка під час надсилання розрахункових листів у систему опрацювання на ftp-сервер: ${0}.

PAYSHEET_VALID_NO_FILE Відсутній один або обидва файли (відомість/довідник) для заливки!

PAYSHEET_VALID_WRONG_CONTENT Помилка у файлі \"${0}\" в рядку ${1}: значення поля ${2} недопустиме! Фактичне значення: \"${3}\". Допустимі значення: \"${4}\".

VALID_COLUMN_NOT_EXISTS Помилка у файлі \"${0}\": відсутнє обов’язкове поле ${1}.

VALID_FIELD_ATTR_ID_NOT_EXISTS Помилка у файлі \"${0}\": відсутнє обов’язкове поле ATTR_ID.

VALID_FIELD_NULL_OR_EMPTY Помилка у файлі \"${0}\" в рядку ${1}: поле ${2} не може бути порожнім!

XLSX_FILE_IS_XXE XLSX-файл містить вразливість і схильний до загрози XXE-атаки!

TABNUM_NOT_PROJECT У файлі 'Відомість' зазначені неправильні табельні номери співробітників. Перевірте табельні номери в меню Виплати, вкладка 'Список отримувачів'.

TABNUM_REQUEST_ERR Вибачте, виникли непередбачені труднощі.

TABNUM_ERR Вибачте, виникли непередбачені труднощі.

PROCESS_UNEXPECTED_ERR Непередбачена помилка під час опрацювання файлів розрахункових листів.

PAYSHEET_PROCESS_EXPECTED_ERR Помилка під час опрацювання файлів розрахункових листів: ${0}.

PAYROLLPROJECTS_REQUEST_ERR Помилка пошуку ЗП проєктів за юр. особою: ${0}.

SERVICE_ERROR_LOCAL_JOURNAL Помилка взаємодії з журналом операцій. ${0}.

PAYSHEET_PROJECT_ACESS_DENIDED У вас відсутній доступ до зарплатного проєкту з референсом: ${0}.

CLIENT_AUTH Доступ заборонений! Необхідна авторизація.

CLIENT_AUTH_DENY Доступ заборонений!

CLIENT_AUTH_BADSESSION Сесія невалідна.

CLIENT_AUTH_P24_CHECK_ERR Помилка процесу авторизації!

CLIENT_AUTH_P24_NOT_VALID Автентифікаційні дані невалідні!

CLIENT_AUTH_ERROR Помилка під час визначення валідності сесії.

9. Корпоративні картки

Усі запити POST (content-type:application/json;charset=utf-8|cp1251)

Зведена інформація за всіма корпораціями для вибраного підприємства

/api/corpcards/summary (застаріле, працює до листопада 2023р)

/api/corpcards/v2/cards/list

Запит:

{

"panState":"o"

}

panState – фільтр (o – показувати тільки картки з відкритим статусом, c – тільки із закритим, пустий об’єкт {} – усі картки).

Відповідь:

{

"Data": {

"JurData": {

"ClientIdJur": 1004410776,

"OKPO": "31435622", // ЄДРПОУ юр. особи

"allCards": 181, // кількість карток у сумі за всіма корпораціями (після застосування всіх фільтрів)

"cardsShown": 100, // кількість карток, показаних у сумі для всіх корпорацій (після застосування всіх фільтрів)

"CorpData": [{

"corpType": "CORP", // тип корпорації*

"CorpCode": "31435622WE", // код корпорації

"Branch": "DNH0", // бранч корпорації

"CorpCcy": 980, // валюта основної картки, числове значення

"jurId": 2144785, // ID юр. особи

"createDate": "2014-03-31 22:03:38", // дата створення

"channel": "PR48", // канал відкриття

"bank": "PB", // банк

"version": 58, // версія даних

"cardsAmount": 27, // кількість карток корпорації (після застосування всіх фільтрів)

"cardsShown": 27, // кількість показаних карток корпорації (після застосування всіх фільтрів)

"MainCardAcc": "26007050229912", // номер основного рахунку головної картки

"MFO_ACC": "305299", // МФО основного рахунку головної картки

"АССState": "a", // стан основного рахунку головної картки

"NameCard": "TEST_V3", // назва корпорації

"CorpCcyS": "980", // валюта основної картки, строкове значення

"MainCardNum": "2600****9912=-638165863", // номер основної картки

"MaskedMainCardNum": "260070****9912", // маска номера основної картки

"iban": "UA623052990000026007050229912", // номер основного рахунку головної картки у форматі IBAN

"grType": null, // бранч торговельної точки

"openingDate": "2019-08-05 00:00:00",

"PanData": [{ // масив карток корпорації

"PanNumber": "4246****0566=923050752", // номер картки

"MaskedPanNumber": "424600******0566", // маска номера картки

"iban": "UA623052990000026007050229912", // рахунок в IBAN-форматі

"ClientIdEkbFiz": 42759601, // ID фіз. особи власника картки

"InnFiz": "3094804424", // ІПН фіз. особи власника картки

"FioFiz": "БЄЛКІНА ЛЮДМИЛА МИКОЛАЇВНА", // П. І. Б. фіз. особи власника картки

"PanCorpCode": "31435622WE", // код материнської корпорації

"PanCcy": 980, // валюта картки, числове значення

"PanState": 12, // статус картки, числове значення

"PanStateS": "c", // статус картки, строкове значення

"PanExpDate": "0923", // термін дії картки

"PanType": "00", // тип карткового продукту

"Balance": 0, // залишок на картці

"DateLastTran": null, // час останньої транзакції

"PanPurse": 3048844, // номер гаманця картки

"Bank": "PB", // банк

"MainCardAcc": "26007050229912", // номер основного рахунку головної картки

"MFO_ACC": "305299", // МФО основного рахунку головної картки

"АССState": "a", // стан основного рахунку головної картки

"NameCard": "TEST_V3", // назва корпорації

"OKPO": "31435622", // ЄДРПОУ юр. особи

"Branch": "DNH0", // бранч

"ClientIdEkbJur": 1004410776,

"JurId": 2144785,

"PanFirstAcc": "4246****6980=-1192040845", // номер первинно відкритого рахунку

"PanCcyS": "980", // валюта картки, строкове значення

"zachVozmEqaer": "N",

"createDate": null,

"channel": "PR48",

"version": 1,

"refContract": "SAMDNWFC00054789713", // референс контракту

"contractType": null, // тип контракту

"main": false, // ознака основної картки

"cardAlias": null, // назва картки

"can": "4246001000000566980",

"isAdd": false,

"believer": false, // ознака вірянин

"documentSeries": null, // серія паспорта

"documentNumber": null, // номер паспорта

"openingDate": "2019-08-05 00:00:00"

* можливі значення – тип корпорації:

Значення	Тип	Критерій
FUEL	Паливна	На основі масок картки 1828* поля MainCardNum
ACCKEY	Ключ до рахунку	На основі масок рахунків 2600, 2650 та 2620* поля MainCardAcc
CORP	Корпоративна	На основі масок рахунків 2605* та 2655* поля MainCardAcc
UNDEF	Недостатньо даних для визначення	Не підпадає під інші критерії

Якщо значення "cardsAmount" і "cardsShown" однакові, це означає, що за цією корпорацією отримані всі картки й запит п. 2 можна не виконувати.

Отримання списку карток за конкретною корпорацією

/api/corpcards/summary (застаріле, працює до листопада 2023р)

/api/corpcards/v2/cards/list

Запит:

{

"panState":"o",

"corpCod":"FUAUW54044"

}

Можливі поля:

corpCod – код корпорації

corpType – тип корпорації

numOfEntr – кількість карток у пакеті (макс. 100)

packNum – номер пакета

panState – фільтр (o – показувати тільки картки зі статусом «Відкрито», c – тільки із закритим статусом)

"main": "Y" - основна корпорація (так, ні)

"cardNumber": null - номер main карти

"search": null - пошук за останніми 4 цифрами карти

Відповідь (опис параметрів аналогічний п. 1):

{

"Data": {

"JurData": {

"ClientIdJur": 1004410776,

"OKPO": "31435622",

"allCards": 4,

"cardsShown": 4,

"CorpData": [{

"corpType": "CORP",

"CorpCode": "W052328107",

"Branch": "HAVK",

"CorpCcy": 980,

"jurId": 2498369,

"createDate": "2019-01-21 13:38:50",

"channel": "PR48",

"bank": "PB",

"version": 1,

"cardsAmount": 4,

"cardsShown": 4,

"MainCardAcc": "26005052328107",

"MFO_ACC": "351533",

"АССState": "l",

"NameCard": "TEST_TEST 137 , 26005052328107",

"CorpCcyS": "980",

"MainCardNum": "2600****8107=1557297500",

"MaskedMainCardNum": "260050****8107",

"iban": "UA513515330000026005052328107",

"grType": null,

"openingDate": "2014-07-30 00:00:00",

"PanData": [{

"PanNumber": "4246****0057=1856359741",

"MaskedPanNumber": "424600******0057",

"iban": "UA513515330000026005052328107",

"ClientIdEkbFiz": 24870184,

"InnFiz": "3350107731",

"FioFiz": "ЛУК''ЯНОВ ВЛАДИСЛАВ МИКОЛАЙОВИЧ",

"PanCorpCode": "W052328107",

"PanCcy": 980,

"PanState": 12,

"PanStateS": "c",

"PanExpDate": "1299",

"PanType": "00",

"Balance": 0,

"DateLastTran": null,

"PanPurse": 5280411,

"Bank": "PB",

"MainCardAcc": "26005052328107",

"MFO_ACC": "351533",

"АССState": "l",

"NameCard": "TEST_TEST 137 , 26005052328107",

"OKPO": "31435622",

"Branch": "HAVK",

"ClientIdEkbJur": 1004410776,

"JurId": 2498369,

"PanFirstAcc": "4246****7980=1863923706",

"PanCcyS": "980",

"zachVozmEqaer": "N",

"createDate": null,

"channel": "PR48",

"version": 1,

"refContract": "SAMDNWFC00054858719",

"contractType": null,

"main": false,

"cardAlias": null,

"can": "4246001030000057980",

"isAdd": false,

"believer": false,

"documentSeries": null,

"documentNumber": null,

"openingDate": "2014-07-30 00:00:00"

}, {

"PanNumber": "4246****0073=1856361597",

"MaskedPanNumber": "424600******0073",

"iban": "UA513515330000026005052328107",

"ClientIdEkbFiz": 24870184,

"InnFiz": "3350107731",

"FioFiz": "ЛУК''ЯНОВ ВЛАДИСЛАВ МИКОЛАЙОВИЧ",

"PanCorpCode": "W052328107",

"PanCcy": 980,

"PanState": 12,

"PanStateS": "c",

"PanExpDate": "1299",

"PanType": "00",

"Balance": 0,

"DateLastTran": null,

"PanPurse": 5280411,

"Bank": "PB",

"MainCardAcc": "26005052328107",

"MFO_ACC": "351533",

"АССState": "l",

"NameCard": "TEST_TEST 137 , 26005052328107",

"OKPO": "31435622",

"Branch": "HAVK",

"ClientIdEkbJur": 1004410776,

"JurId": 2498369,

"PanFirstAcc": "4246****3980=1861957500",

"PanCcyS": "980",

"zachVozmEqaer": "N",

"createDate": null,

"channel": "PR48",

"version": 1,

"refContract": "SAMDNWFC00054903147",

"contractType": null,

"main": false,

"cardAlias": null,

"can": "4246001030000073980",

"isAdd": false,

"believer": false,

"documentSeries": null,

"documentNumber": null,

"openingDate": "2014-07-30 00:00:00"

} ]

}

]

}

Далі також аналізуються поля:

"cardsAmount": 4,

"cardsShown": 4,

в разі потреби отримання наступного пакета карток

Виписка за групою карток

/api/corpcards/statements/groupcards (застаріле, працює до листопада 2023р)

/api/corpcards/v2/corp/statements?dateStart=01.01.2023&dateEnd=01.01.2023

Запит: (застарілий)

{

"panState":"o",

"corpBranch": "DNH8-FUAUW54044",

"dateStart": "01-01-2015",

"dateEnd": "01-01-2019"

}

Можливі поля:

corpBranch – <бранч>-<код корпорації>

dateStart – дата початку періода

dateEnd – дата кінця періода

Запит: (для нового api)

{

"corporation":

{

"id": "id",

"code": "code",

"type": "CORP"

}

Можливі поля:

id - id корпорації ("ClientIdJur" або Branch у відповіді з п.1)

code - код корпорації (CorpCode у відповіді з п.1)

type - тип корпорації (corpType у відповіді з п.1)

Відповідь:

{

"CorpStatement": {

"panInfos": [{

"pan": "4246****0566=923050752", // номер картки

"fio": "БЕЛКИНА ЛЮДМИЛА НИКОЛАЕВНА" // П. І. Б. власника картки

…………………...

"statements": [{

"idFront": "0", // фронтальний ID транзакції

"linked": "true", // ознака прив’язаної картки

"entryType": "S", // тип операції

"mcc": "6012", // код MCC

"code": "B33", // код операції

"tranRef": "27338544157", // референс транзакції

"approval": "035281", // код авторизації

"account": {

"ccy": "980", // валюта картки

"card": "5169****2484=-2057990465", // номер картки

"name": "", // ім’я та адреса термінала

"acc": "5169****2484=-2057990465" // номер картки, рахунку

"fee": "0.00", // розмір комісії

"amountAmt": "0.04", // сума операції у валюті картки

"amountCcy": "UAH", // валюта операції

"originalAmt": "0.04", // сума у валюті операції

"originalCcy": "UAH", // валюта операції

"descr": "Перевод средств при расторжении договора", // призначення операції

"posted": "16.08.2019", // дата опрацювання

"rest": "0.00", // баланс після операції (для проєкту «Ключ до рахунку» цей тег відсутній)

"discount": "0.00", // розмір знижки (для дисконтної програми «Бонус+» є ознака: <discount type="BONUSPLUS">Розмір знижки бонус+</discount>)

"country": "UKR", // країна операції

"details": "{{DID=PB_EN_WFPM2019 **** **** 76224}}N-SMS PEREBROSKA SREDSTV PRI RASTORZHENII DOGOVORA #ZKF# КРЕДИТНАЯ ЧАСТЬ P2P ПЕРЕВОДА", // деталі (опис) операції

"trandc": "CR", // ознака дебет/кредит (DB/CR)

"valuedateId": "20190816T21:00:15", // дата операції (у форматі 20070326T00:00:00)

"valuedateValue": "16.08.2019" // дата операції (у форматі 16.08.2019)

…………………..

]

}

Виписка за карткою

/api/corpcards/statements/card (застаріле, працює до листопада 2023р)

/api/corpcards/v2/card/statements?dateStart=01.01.2023&dateEnd=01.01.2023

Запит: (застарілий)

{

"panState":"o",

"corpBranch": "DNH8-FUAUW54044",

"dateStart": "01-01-2015",

"dateEnd": "01-01-2019",

"panNumber": "1826****5230=627533164"

}

Можливі поля:

corpBranch – <бранч>-<код корпорації>

dateStart – дата початку періода

dateEnd – дата кінця періода

panNumber – замаскований номер картки із поля PanNumber запиту п. 1

Запит: (для нового api)

{

"corporation":

{

"id": "id",

"code": "code",

"type": "CORP"

"clientCard": "1234****6789=123456789"

}

Можливі поля:

id - id корпорації ("ClientIdJur" або Branch у відповіді з п.1)

code - код корпорації (CorpCode у відповіді з п.1)

type - тип корпорації (corpType у відповіді з п.1)

clientCard - замаскований номер картки із поля PanNumber запиту п. 1

Відповідь: (опис параметрів аналогічний п. 3)

{

"CardStatement": {

"statements": [{

"idFront": "35750201089",

"linked": "false",

"entryType": "S",

"mcc": "4829",

"code": "P10",

"tranRef": "27071074263",

"approval": "456099",

"account": {

"ccy": "UAH",

"card": "5169****3849=2080846721",

"name": "",

"acc": "5169****3849=2080846721"

"fee": "0.00",

"amountAmt": "-0.01",

"amountCcy": "UAH",

"originalAmt": "0.01",

"originalCcy": "UAH",

"descr": "Перевод между своими картами/счетами. Комментарий к платежу: Perevod sredstv",

"posted": "01.08.2019",

"rest": "12.36",

"discount": "0.00",

"country": "UKR",

"trandc": "DB",

"valuedateId": "20190801T17:14:36",

"valuedateValue": "01.08.2019"

}, {

"idFront": "35749948186",

"linked": "false",

"entryType": "S",

"mcc": "4829",

"code": "P10",

"tranRef": "27070943940",

"approval": "936098",

"account": {

"ccy": "UAH",

"card": "5169****3849=2080846721",

"name": "",

"acc": "5169****3849=2080846721"

"fee": "0.00",

"amountAmt": "-0.01",

"amountCcy": "UAH",

"originalAmt": "0.01",

"originalCcy": "UAH",

"descr": "Перевод между своими картами/счетами. Комментарий к платежу: Perevod sredstv",

"posted": "01.08.2019",

"rest": "12.37",

"discount": "0.00",

"country": "UKR",

"trandc": "DB",

"valuedateId": "20190801T17:03:28",

"valuedateValue": "01.08.2019"

}

"maxDate": "14.10.2019",

"panMain": "5169****3849=2080846721",

"summary": {

"acc": "5169****9980=-1418431696",

"panmain": "5169****3849=2080846721",

"holderClientId": "51539074",

"holderValue": "ОРЛЯНСЬКИЙ ОЛЕКСІЙ АНДРІЙОВИЧ",

"brest": "12.38",

"erest": "12.36",

"db": "0.02",

"cr": "0.00",

"fee": "0.00",

"discount": "0.00"

}

10. Інструкція. Як додати співробітника, надати йому дозволи та отримати КЕП

Щоб додати співробітника, потрібно виконати такі дії:

Отримати КЕП можна таким способом:

Також у мобільному додатку «Приват 24 для бізнесу» можна отримати хмарний КЕП – SmartID. Для цього слід виконати такі дії: