Опис API для взаємодії із серверною частиною додатка «Автоклієнт»
версія 3.0.0
Створення профілю та отримання даних для авторизації
Завантаження документів XML (без ЕЦП) (в т.ч. це ІНВОЙСИНГ)
Завантаження документів XML з одночасним надсиланням контрагентові з ЕЦП (в т.ч. це ІНВОЙСИНГ)
Завантаження документів PDF (без ЕЦП)
Завантаження документів PDF до Base64 (без ЕЦП)
Надсилання контрагентові завантаженого непідписаного документа
Створення платежу на основі рахунка-фактури
Отримання Base64-документа (для підписання)
Отримання інформації щодо ЕЦП на документі
Отримання документа з ЕЦП (використовується для XML-документів) у форматі .p7s
Отримання списку доступних груп
Додавання нового співробітника до групи SALARY/STUDENT
Додавання отримувача у відомість
Видалення отримувача з відомості
Надсилання відомості maspay на перевірку
Створення нової відомості maspay
Додатки:
Важлива інформація!
Не передавайте токен третім особам. Якщо плануєте зберігати чи використовувати токен не на своєму сервері або додатку, ознайомтеся з їхньою політикою конфіденційності та інформацією про безпеку, щоб дізнатися, як вони будуть використовувати й захищати ваші дані.
Протоколи tls 1.0 та 1.1 не підтримуються! Рекомендуємо використовувати tls 1.3
Сервіс доступний для юр. осіб в тарифах “Бізнес Комфорт” та “Бізнес Про” Для ФОП сервіс доступний в будь якому тарифі.
Створення профілю та отримання даних для авторизації
Щоб одержати авторизаційні дані, потрібно підключити додаток «Автоклієнт», як зазначено в інструкції (пункти 1 та 2). Далі натиснути кнопку «Підключити додаток» і вибрати з розкривного списку API.
Ввести назву додатка та IP-адреси (за потреби), ознайомитися з умовами й правилами використання, поставити прапорець і натиснути кнопку «Зберегти».
Після створення додатка API потрібно перейти до налаштувань, натиснувши на . Ознайомитися з умовами використання та натиснути кнопку «Ознайомлений(а)».
У модальному вікні скопіювати token (достатньо натиснути на піктограму ліворуч від слова token).
Натиснувши кнопку «Отримати авторизаційні дані в старому форматі», ви можете одержати окремо ID та token.
Взаємодія з API
Усі запити повинні містити обов’язкові поля в header:
Підтримувані кодування 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 наступної пачки з відповіді (необов'язковий параметр)
&limit=кількість записів у пачці (за замовчуванням 20), максимальне значення - 500, рекомендується використовувати не більше 100
Отримати дані за останній підсумковий день:
https://acp.privatbank.ua/api/statements/balance(или transactions)/final
?acc=номер рахунку
&followId=id наступної пачки з відповіді (необов’язковий параметр)
&limit=кількість записів у пачці (за замовчуванням 20), максимальне значення - 500, рекомендується використовувати не більше 100
Якщо номер рахунку не зазначено (немає параметра 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"
}
}
}
Де:
З прогнозом: https://acp.privatbank.ua/api/proxy/payment/create_pred
Без прогнозу: https://acp.privatbank.ua/api/proxy/payment/create
BODY
Тіло запиту – це JSON-об’єкт із реквізитами платежу. Усі реквізити типу string.
Обов’язкові реквізити:
У випадку, якщо отримувач не має ЄДРПОУ (ФОП віруючий), в полі recipient_nceo вказується 0000000000 та додатково передаються дані паспорту:
Для ID паспорту замість номеру та серії паспорту необхідно передававати наступний параметр:
Необов’язкові реквізити (їх може не бути):
Приклад тіла запиту
{
"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"
}
Коди можливих помилок:
Опрацювання помилок
У разі виникнення помилки сервер повертає JSON-об’єкт виду:
{
"status": "ERROR",
"code": "400",
"message": "invalid document number",
"requestId": "20240223_131617_286f",
"serviceCode": "PMTSRV0112"
}
Коди HTTP-відповідей у разі виникнення помилок:
«Приват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 // До сплати
Параметри запиту з прикладами значень
Обов’язкові:
Необов’язкові (в дужках зазначено номер примітки):
Примітки
Значення параметра є масивом необмеженої кількості валідних 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 статус підписано (Кінцевий покупець)
Формат відповіді з помилкою
Можливі коди відповіді:
Приклад тіла відповіді з помилкою
{
"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
Параметри:
Приклад успішної відповіді
{
"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
Параметри:
Приклад відповіді
{
“id”: ID створеного й надісланого документа
“TEMP_LINK”: “тимчасове посилання на документ (якщо під час надсилання не було передано 0)”
}
Завантаження документів PDF (без ЕЦП)
content-type: multipart/form-data
POST-запит
/api/proxy/edoc/loader/upload-pdf
Параметри:
Приклад успішної відповіді
{
"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
Параметри:
Приклад успішної відповіді
{
"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
Параметри:
Приклад успішної відповіді
{
"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
Параметри:
Приклад успішної відповіді
{
"STATUS":"SUCCESS"
}
Створення платежу на основі рахунка-фактури
POST-запит
/api/proxy/edoc/create-payment-from-invoice/{id}?okpo=okpo&payerAccount=payerAccount
Параметри:
Приклад успішної відповіді
{
STATUS: SUCCESS
}
Видалення документа
GET-запит
/api/proxy/edoc/journal/delete/ID?okpo=okpo
Параметри:
Отримання XML-документа (application/octet-stream)
GET-запит
/api/proxy/edoc/journal/get-xml-document/ID?okpo=okpo
Параметри:
Отримання Base64-документа (для підписання) (application/json)
GET-запит
/api/proxy/edoc/journal/get-base64/ID?okpo=okpo
Параметри:
Відповідь
{
fileName: ім’я файлу
originalDoc: документ у base64
}
Отримання PDF-документа (application/octet-stream)
GET-запит
/api/proxy/edoc/journal/get-pdf-document/ID?okpo=okpo
Параметри:
Отримання інформації щодо ЕЦП на документі
GET-запит
/api/proxy/edoc/journal/sign-info/ID?okpo=okpo
Параметри:
Отримання документа з ЕЦП (використовується для XML-документів) у форматі .p7s
GET-запит
/proxy/edoc/journal/get-p7s/ID?okpo=okpo
Параметри
«Приват24 для бізнесу» (меню «Каталог послуг» – «Електронна звітність»)
Завантаження (upload) документів
content-type: multipart/form-data
POST-запит
/api/proxy/eo/documents/create
Параметри:
Завантаження (upload) документів (у форматі Base64)
content-type: application/x-www-form-urlencoded
POST-запит
/api/proxy/eo/documents/create-b64
Параметри:
* duplicate – визначає поведінку ЕО під час спроби створити документ з ідентифікатором у зовнішній системі, з яким в ЕО раніше вже був створений інший документ.
Прийняті значення:
Якщо вже створений документ було підписано та надіслано в державні органи, параметр буде проігноровано й буде повернуто помилку.
Успішна відповідь
{
“result”: “success”,
“documents”: [
{
"id": "{ідентифікатор документа в Зовнішній системі}",
“result”: “success”
} ]
}
Відповідь із помилкою
{
“result”: “error”,
"error_message": “{текст помилки}"
{
«Приват24 для бізнесу» (меню «Каталог послуг» – «Зарплатні та інші виплати»)
Сервіс працює лише зі співробітниками. Для початку роботи рекомендовано отримати перелік співробітників у зарплатному проекті та зберегти їх. При оновленні даних по співробітникам у зарплатному проекті (додано нового співробітника, оновились дані по поточному та ін.) необхідно відправити запит на отримання списку одержувачів та оновити дані.
Для додавання співробітників можна відправити запит на створення відомості, зберегти отриманий референс і додавати необхідних співробітників у створену відомість (вказавши відповідний референс відомості). Також можна отримати перелік вже існуючих відомостей і додавати співробітників у вже існуючу відомість, також вказавши відповідний референс відомості.
Після успішної роботи з додавання співробітників можна відправити відомість на перевірку, або зробити це у Приват24 для бізнесу. Підписати та відправити відомість можна лише у Приват24 для бізнесу.
Групи – аналог зарплатних проєктів. У межах однієї юридичної особи не може бути більше ніж одна група одного типу.
Отримання списку доступних груп
GET | /api/pay/mp/list-groups |
JSON | [ { “type”: “SALARY”, “name”: “ім’я проекта”, “rko”: 0.05 }, ... ] |
Type – це тип групи, що може бути одним із таких, але не виключно (не можна припускати, що тільки ці та жодні інші):
Поле 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, з підвантаженням, доки список не буде порожнім.
Функції безпосереднього додавання в моделі немає. Додавання поєднане з оновленням, тому 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, ревізія> }, ... ] |
Де використовуються такі параметри:
У структурі відповіді потрібно звернути увагу на такі поля:
У кожної підсистеми своє 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 | Пакет видалено |
GET | /api/pay/maspay/<референс пакета>/header |
JSON | { “reference”: “референс відомості”, “createdAt”: “дата створення”, “finishedAt”: “дата обробки”, “group”: “код групи”, “status”: “стан відомості”, “substatus”: “розширений стан відомості”, “packetName”: “назва відомості”, “errText”: “текст помилки пов’язаний відомістю”, “recordCount”: <10, кількість записів>, “recordAmount”: <10.33, повна сума відомості>, “revision”: <123, ревізія> } |
GET | /api/pay/maspay/<референс пакета>/content?page=0&page-size=100 |
JSON | [ { “ref”:”<референс запису>”, “fio”:”ПІБ отримувача”, “inn”:”ІПН отримувача”, “cardNumber”:”маскований номер”, “comment”:”призначення виплати”, “amount”:<сума виплати>, “status”: “<статус запису>”, “errorCode”:”<код помилки>”, “tabNo”: “табельний номер” }, ... ] |
Де:
Статус | Коментар |
N | Запис ще не перевірявся |
N$ | У записі є помилка, яку можна виправити у вебверсії «Приват24 для бізнесу» (наприклад 0 сума) |
R | Успішно перевірено |
M | Успішно сплачено |
E | Забраковано |
* | Усе інше можна вважати помилками, на які неможливо вплинути |
POST | /api/pay/maspay/<референс пакета>/add |
REQ JSON | { “receiver”: “<id отримувача>” “comment”:”призначення виплати”, “amount”:<сума виплати> } |
RESP JSON | { “ref”: “<реф. нового запису>” } |
Де:
Можливі помилки:
maspay:L_PACKET_OVERFLOW у разі перевищення розміру відомості;
mp:* можливі помилки від УЗ.
POST | /api/pay/maspay/<референс пакета>/remove |
REQ JSON | { “ref”: “<референс запису>” } |
RESP JSON | {
} |
Де:
POST | /api/pay/maspay/<референс пакета>/validate |
RESP JSON | див. maspay//header |
На перевірку надсилаються пакети в статусі N. Для статусу W запит ігнорується, інше – помилка. Підтвердженням запуску перевірки є status='P' відповіді.
POST | /api/pay/maspay/create |
REQ JSON | { “group”: “SALARY|STUDENT”, “salary”: true|false, [“packetName”: “заголовок відомості”] } |
RESP JSON | див. maspay//header |
Де:
Будь-який запит до maspay може викликати такі помилки:
{
"status": "err",
"error": {
"system": "isa",
"code": "V_BAD_PARAM",
"args": [
"from"
],
"ref": "39278f1a-cdec-496d-947d-f70dcb84bbd9"
}
}
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”
}
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 Помилка під час визначення валідності сесії.
Усі запити 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. Для цього слід виконати такі дії: