Опис API Інформаційно-телекомунікаційної системи «Електронний кабінет»
API – прикладний програмний інтерфейс.
Інформаційно-телекомунікаційна система (далі – ІТС) – сукупність інформаційних та телекомунікаційних систем, які у процесі обробки інформації діють як єдине ціле;
Кабінет – доопрацьований ІТС «Електронний кабінет» у вигляді електронного сервісу забезпечення взаємодії органів державної фіскальної служби та платників податків та системи публікації даних в мережі Інтернет;
Вихідна інформація – інформація, отримана в результаті виконання функцій ІТС;
Вхідна інформація – інформація, що надходить до ІТС у вигляді документів, повідомлень сигналів та є необхідною для виконання функцій ІТС;
Дані – інформація, подана у формалізованому вигляді, придатному для пересилання, інтерпретування чи оброблення за участю людини або автоматичними засобами;
1. Опис REST API
1.1. Загальна інформація
API або прикладний програмний інтерфейс (англ. Application Programming Interface,) - це набір визначень взаємодії різнотипного програмного забезпечення. У ІТС «Електронний кабінет» за допомогою АРІ забезпечується взаємодія з Кабінетом різноманітного існуючого програмного забезпечення щодо подання звітності та забезпечення документообігу між ДФС і іншими органами влади, наприклад Міністерством юстиції України.
1.2. Взаємодія через програмний інтерфейс REST АРІ
REST (скор. англ. Representational State Transfer, «передача репрезентативного стану») — підхід до архітектури мережевих протоколів, які забезпечують доступ до інформаційних ресурсів.
Дані передаються у вигляді стандартного формату JSON (до якого вкладено зашифрований Base64 XML документ). REST протокол підтримує кешування, не залежить від мережевого прошарку та не зберігає інформацію про стан між парами «запит-відповідь». Такий підхід забезпечує масштабовність системи і дозволяє їй еволюціонувати з новими вимогами.
Робота АРІ Кабінету організована наступним чином:
Розташування у мережі Internet:
Вузол: cabinet.sfs.gov.ua
Основной шлях: /cabinet/public/api/exchange
Повний шлях: https://cabinet.sfs.gov.ua/cabinet/public/api/exchange/
Використані теги:
• report-controller: Report Controller
1.2.1. Надсилання звіту за допомогою REST АРІ
Метод, що використовується: POST.
Додатковий шлях (додається до основного або повного шляху): /report
Використані теги:
• report-controller: incomingReport
Параметри:
| Тип
| Ім'я
| Опис | Обов'язковість | Схема
| За замовчанням |
| BodyПараметр | list | list | true | InReportDao array |
|
Відповіді:
| HTTP код
| Опис | Схема |
| 200 | OK | ReturnReport |
| 201 | Created | No Content |
| 401 | Unauthorized | No Content |
| 403 | Forbidden | No Content |
| 404 | Not Found | No Content |
Приймає - application/json
Повертає - json за тим же шляхом
1.2.2. Надсилання архіву зі звітами (пакету) за допомогою REST АРІ
Метод, що використовується: POST
Додатковий шлях (додається до основного): /reportzip
Використані теги:
• report-controller: incomingReportZip
Параметри:
| Тип
| Ім'я
| Опис | Обов'язковість | Схема
| За замовчанням |
| BodyПараметр | zipBase64 | zipBase64 | true | InReportDao array |
|
Відповіді:
| HTTP код
| Опис | Схема |
| 200 | OK | ReturnReport |
| 201 | Created | No Content |
| 401 | Unauthorized | No Content |
| 403 | Forbidden | No Content |
| 404 | Not Found | No Content |
Приймає - application/json
Повертає - application/json
1.2.3. Отримання квитанцій за допомогою REST АРІ
Метод, що використовується: POST
Додатковий шлях (додається до основного): /kvt_by_id
Використані теги:
• report-controller: ІncomingReport
Параметри:
| Тип
| Ім'я
| Опис | Обов'язковість | Схема
| За замовчанням |
| BodyПараметр | encryptedId | encryptedId | true | string |
|
Відповіді:
| HTTP код
| Опис | Схема |
| 200 | OK | ReturnReport |
| 201 | Created | No Content |
| 401 | Unauthorized | No Content |
| 403 | Forbidden | No Content |
| 404 | Not Found | No Content |
Приймає -• application/json
Повертає - json за тим же шляхом
1.2.4. Визначення
InReportDao
| Ім’я | Опис | Обов’язковість | Схема | За замовчанням |
| contentBase64 | зміст | false | string |
|
| fname | назва файлу | false | string |
|
ReturnKvt
| Ім’я | Опис | Обов’язковість | Схема | За замовчанням |
| finalKvt | ознака | false | integer (int32) |
|
| kvtBase64 | зміст | false | string |
|
| kvtFname | назва файлу квитанції | false | string |
|
| numKvt | Номер квитанції | false | integer (int32) |
|
| status | статус | false | integer (int32) |
|
ReturnReport
| Ім’я | Опис | Обов’язковість | Схема | За замовчанням |
| id | ідентифікатор | false | integer (int64) |
|
| kvt1Base64 | зміст | false | string |
|
| kvt1Fname | назва файлу квитанції | false | string |
|
| kvtList | перелік квитанцій | false | ReturnKvt array |
|
| message | сповіщення | false | string |
|
| status | статус | false | enum (OK, ERROR, ERROR_DECRYPT, ERROR_STRUCT_R EPORT, ERROR_LINKED_D OCS, ERROR_DB, ERROR_SERTIF_O RG, ERROR_SERTIF, ERROR_XSD, NOT_KVT) |
|
