Опис 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

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

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

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)