Опис API Електронного кабінету

API або прикладний програмний інтерфейс (англ. Application Programming Interface,) - це набір визначень взаємодії різнотипного програмного забезпечення. «Електронний кабінет» за допомогою АРІ забезпечує взаємодію з різноманітним програмним забезпеченням, що реалізує функції подання звітності до органів податкової служби, та забезпечує документообіг між ДПС і іншими органами влади.

ІТС «Електронний кабінет» надає наступні API:

  1. Подання звітності, заяв, запитів та реєстрація податкових і акцизних накладних
  2. Передача банками інформації про відкриття/закриття рахунків
  3. Фіскалізація чеків та передачя Z-звітів в рамках експериментального проекту РРО

Подання звітності, заяв, запитів та реєстрація накладних

  1. Взаємодія через програмний інтерфейс REST АРІ

REST (скор. англ. Representational State Transfer, «передача репрезентативного стану») — підхід до архітектури мережевих протоколів, які забезпечують доступ до інформаційних ресурсів.

Дані передаються у вигляді стандартного формату JSON (до якого вкладено зашифрований Base64 XML документ).

Робота АРІ Кабінету організована наступним чином:

Розташування у мережі Internet:

Вузол: https://cabinet.tax.gov.ua

Основной шлях: /cabinet/public/api/exchange

Повний шлях: https://cabinet.tax.gov.ua/cabinet/public/api/exchange/

Альтернативний текст

Загальна схема взаємодії з API

1.1. Надсилання звіту за допомогою REST АРІ

Метод, що використовується: POST.

Додатковий шлях (додається до основного або повного шляху): /report

Використані теги:

  • report-controller: incomingReport
Параметри
Тип Ім’я Обов’язковt Схема Опис
Body Parameters list true
InReportDao
array
Передається масив contentBase64, fname
contentBase64 - підписаний та
зашифрований xml-документ, fname
файлу XML

Правила формування та іменування XML-файлів звітності (параметр fname) описані у Форматі (стандарті) електронного документа звітності суб’єктів господарювання, що затверджений наказом Міндоходів від 29.11.13 № 729: http://sfs.gov.ua/elektronna-zvitnist/platnikam-podatkiv-pro/normativne-zabezpechennya/63127.html

Реєстр форм електронних документiв, опис полів та схем контролю XML-документів (XSD) доступний за посиланням http://sfs.gov.ua/data/material/000/006/58768/Forms_deklar.htm

Сформоманий XML-документ повинен бути підписаний, зашифрований та переданий в параметрі contentBase64 в узагальненому форматі транспортного контейнера для передачі документів до податкового органу, що затверджений наказом Деражвної податкової ажміністрації від 12.07.2010 № 499: https://zakon.rada.gov.ua/rada/show/v0499225-10

Відповіді
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. Надсилання архіву зі звітами (пакету) за допомогою REST АРІ

Метод, що використовується: POST

Додатковий шлях (додається до основного): /reportzip

Використані теги:

  • report-controller: incomingReportZip
Параметри
Тип Ім’я Опис Обов’язковість Схема
Body Parameter 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.3. Отримання квитанцій за допомогою REST АРІ

Метод, що використовується: POST

Додатковий шлях (додається до основного): /kvt_by_id

Використані теги:

  • report-controller: ІncomingReport
Параметри
Тип Ім’я Опис Обов’язковість Схема
Body encryptedId encryptedId true String
Parameter        
Відповіді
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.4. Визначення

InReportDao

InReportDao
Ім’я Опис Обов’язковість Схема
contentBase64 дані false string
fname назва файлу false string

ReturnKvt

ReturnKvt
Ім’я Опис Обов’язковість Схема
finalKvt ознака false integer (int32)
kvtBase64 дані false string
kvtFname назва файлу false string
numKvt Номер квитанції false integer (int32)
status статус false integer (int32)

ReturnReport

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_REPORT, ERROR_LINKED_DOCS, ERROR_DB, ERROR_SERTIF_ORG ERROR_SERTIF, ERROR_XSD, NOT_KVT)

Передача банками інформації про відкриття/закриття рахунків

API для передача банками інформації про відкриття/закриття рахунків повністю ідентичне API «Подання звітності, заяв, запитів та реєстрація накладних» з урахуванням таких особливостей:

  1. Додатковий шлях (додається до основного або повного шляху): /reportBank
  2. Правила формування та іменування XML-файлів повідомлень про відкриття/закриття (параметр fname) описані у наказі Міністерства фінансів України від 09.07.2019 № 292 «Про внесення змін до Порядку подання повідомлень про відкриття/закриття рахунків платників податків у банках та інших фінансових установах до контролюючих органів» https://zakon.rada.gov.ua/laws/show/z0832-19l

Опис API Електронного кабінету для фіскалізації чеків та передачі Z-звітів

  1. API Електронного кабінету для фіскалізації чеків та передачі Z-звітів доступне за адресою https://cabinet.tax.gov.ua:8443, та реалізоване на фреймворку gRpc, розробленому компанією Google, Висока продуктивність досягається за рахунок використання протоколу HTTP/2 и Protocol Buffers, детальніше за посиланням: https://grpc.io/
  2. Опис методів API

Передача чеку чи Z-звіту:

Check{
         data( Bytes "windows-1251" ) - чек або z-звіт у форматі XML, підписаний внутрішнім підписом з позначкою часу
         fn - фіскальный номер апарата
         number — локальний номер чека
         date - дата/час створення чека (yyyyMMddHHmmss)
         type - тип 1 чек , 2 Z-звіт
         id_cancel - ІД чека повернення
      }

XML-формат чеку та Z-звіту повинен відповідати документу “Система зберігання та збору даних реєстраторів розрахункових операцій. Протокол передачі інформації.”, опублікованому на офіційному веб-порталі Державної податкової служби України: https://tax.gov.ua/data/material/000/311/399207/SZZD_RRO_Protokol_peredach_nformats_2_1_7.doc

Cформоманий XML-документ повинен бути підписаний, зашифрований та переданий в параметрі contentBase64 в узагальненому форматі транспортного контейнера для передачі документів до податкового органу, що затверджений наказом Деражвної податкової ажміністрації від 12.07.2010 № 499: https://zakon.rada.gov.ua/rada/show/v0499225-10

Відповідь API:

Answer
  id - ID (фіскальний номер) чеку
  Status{
         UNKNOWN = 0; не визначений
         OK = 1;
         ERROR_VEREFY = -1; - помилка перевірки підпису
         ERROR_CHECK = -2; - помилка перевірки РРО
         ERROR_SAVE = -3; - помилка запису
         ERROR_UNKNOWN = -4; - загальна помилка
         ERROR_TYPE = -5; - помилка типу посилки
         ERROR_NOT_PREV_ZREPORT = -6; - нема Z-звіта
         ERROR_XML = -7; - невірний формат XML ( структура , фіскальний номер)
         ERROR_XML_DATE = -8; - невірний формат XML дата не відповідає Check.date
         ERROR_XML_CHK = -9; - невірний формат XML чеку
         ERROR_XML_ZREPORT = -10; - невірний формат XML чеку, Z-звіту
         }
  id_sign  - підписаний ID (фіскальний номер) чеку

3. Опис інтерфейсів

syntax = "proto3";

option java_multiple_files = true;
package com.programika.rro.ws.chk;

message Chk {
 string fn = 1;
 int64 date_time = 2;
 bytes check_sign = 3;
 int32 number = 4;
 enum Type {
     UNKNOWN = 0;
     CHK = 1;
     ZREPORT = 2;
 }
 Type type = 5;
 string id_cancel = 6;
 }

 message Answer {
 string id = 1;
 enum Status {
     UNKNOWN = 0;
     OK = 1;
     ERROR_VEREFY = -1;
     ERROR_CHECK = -2;
     ERROR_SAVE = -3;
     ERROR_UNKNOWN = -4;
     ERROR_TYPE = -5;
     ERROR_NOT_PREV_ZREPORT = -6;
     ERROR_XML = -7;
     ERROR_XML_DATE = -8;
     ERROR_XML_CHK = -9;
     ERROR_XML_ZREPORT = -10;
 }
 Status status = 2;
 bytes id_sign = 3;
 }

 service ChkIncomeService {
 rpc sendChk (Chk) returns (Answer);
 rpc ping (Chk) returns (Answer);
 }