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

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

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

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

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

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

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://tax.gov.ua/elektronna-zvitnist/platnikam-podatkiv-pro/normativne-zabezpechennya/63127.html

Реєстр форм електронних документів, опис полів та схем контролю XML-документів (XSD) доступний за посиланням http://tax.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 String
Відповіді
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-19

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

API взаємодії фіскального сервера ДПС та програмних РРО доступне за адресою https://prro.tax.gov.ua:443 .

Тестове API для розробників доступне за адресою https://cabinet.tax.gov.ua:9443 . Увага! Чеки, Z-звіти, що передаються на тестове API, не є фіскальними.

Зміна відкрита / зміна закрита

При першому старті програми зміна закрита. Відкриття зміни відбувається направленням від ПРРО до ФСКО (в онлайні) або до тимчасового ланцюжка непереданих чеків (в офлайні) повідомлення «відкриття зміни» («нульового чеку», у якого локальний номер = 0). Відкриття зміни відбувається вручну (кнопкою на ПРРО).

Попередження

При надходженні повідомлення виконується перевірка чи відкрито зміну на іншому ПРРО вказаним касиром/старшим касиром. У разі відкриття зміни касиром/старшим касиром (з таким ідентифікатором ключа електронного підпису) на іншому ПРРО та зміна на якому не закрита – на таке повідомлення надається відмова у відкритті зміни із зазначенням фіскального номера ПРРО на якому вказаним касиром/старшим касиром не закрито зміну.

Попередження

Після відкриття зміни всі чеки мають бути підписані одним підписом.

Закриття зміни відбувається направленням від ПРРО до ФСКО (в онлайні) або до тимчасового ланцюжка непереданих чеків (в офлайні) Z-звіту. Закриття зміни в офлайні не рекомендоване, але в разі потреби, якщо програмний РРО вміє розрахувати Z-звіт, таке закриття можна виконати. Ініціювання закриття зміни відбувається вручну (кнопкою на ПРРО). Рекомендовано реалізувати в програмному РРО автоматичне інформування користувача про необхідність закрити зміну у визначених ситуаціях (зміна триває більше 24 годин; перед надсиланням першого чеку наступного за днем відкриття поточної зміни дня – визначає розробник програмного РРО для зручності користувачів, з дотриманням вимог законодавства).

Попередження

Зміну замість касира може закрити старший касир.

API реалізоване на фреймворку gRPC (Google Remote Procedure Calls, <https://grpc.io/>). Використовується синтаксис «proto3».

Для всіх операцій, в тому числі для відкриття зміни, відправлення чеку,відправлення Z-звіту (в онлайні і в офлайні), запиту додаткових фіскальних номерів, а також для повідомлень про перехід в офлайн та про перехід в онлайн використовується метод «sendChk», з повідомленням «Check» та відповіддю «CheckResponse».

Попередження

Метод rpc sendChk (Check) returns (CheckResponse) діє до 01.10.2021.

З 01.10.2021 потрібно використовувати метод rpc sendChkV2 (Check) returns (CheckResponse);

Для відкриття зміни – локальний номер чека повинен дорівнювати нулю. Для перевірки зв’язку - локальний номер чека повинен дорівнювати 0x7FFFFFFF (максимальне значення int32, в реальній зміні не може бути більше 2 мілліардів чеків за зміну).

Контроль послідовності та відсутності змін у чеках здійснюється додаванням у XML кожного чеку у повідомленнях «Check» (крім «перевірки зв’язку) хешу XML з попереднього повідомлення «Check».

Для перевірки зв’язку використовується метод ping (Check) який повертає CheckResponse та XMLз типом <CT=»111»>. MAC не заповнюєтеся.

Для отримання останнього чеку використовується метод lastChk (CheckRequest) який повертає (CheckResponse) в полі data_sign знаходиться останній чек.

У випадку необхідності вилучення чеку використовується метод delLastChk. Можна використовувати тільки 1 раз і тільки для чеку продажу. У випадку обриву зв’язку та переходу в офлайн режим.

У випадку необхідності вилучення чеку по ІД використовується метод delLastChkId. Можна використовувати тільки 1 раз і тільки для чеку продажу. Якщо ІД відповідає останньому чеку – чек буде вилучено.

Для отримання статусу ПРРО метод rpc statusRro (CheckRequest) returns (StatusResponse);

Для отримання детальної інформації про ПРРО rpc infoRro (CheckRequest) returns (RroInfoResponse);

Електронний документ про відкриття зміни реєструється фіскальним сервером шляхом присвоєння йому номера.

Додаткова інформація Програмні РРО https://tax.gov.ua/baneryi/programni-rro/

  1. Опис методів API

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

message Check {
    string rro_fn = 1;
    int64 date_time = 2;
    bytes check_sign = 3;
    int32 local_number = 4;
    enum Type {
        UNKNOWN = 0;
        CHK = 1;
        ZREPORT = 2;
        SERVICECHK = 3;
    }
    Type check_type = 5;
    string id_offline = 6;
    string id_cancel = 7;

}

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

Cформоманий XML-документ повинен бути підписаний, та переданий в параметрі check_sign

Відповідь API:

message CheckResponse {
    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;
        ERROR_OFFLINE_168 = -11;
        ERROR_BAD_HASH_PREV = -12;
        ERROR_NOT_REGISTERED_RRO = -13;
        ERROR_NOT_REGISTERED_SIGNER = -14;
        ERROR_NOT_OPEN_SHIFT = -15;
        ERROR_OFFLINE_ID = -16;
    }
    Status status = 2;
    bytes id_sign = 3;
    bytes data_sign = 4;
    string error_message = 5;
}

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

syntax = "proto3";

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


message Check {
    string rro_fn = 1;
    int64 date_time = 2;
    bytes check_sign = 3;
    int32 local_number = 4;
    enum Type {
        UNKNOWN = 0;
        CHK = 1;
        ZREPORT = 2;
        SERVICECHK = 3;
    }
    Type check_type = 5;
    string id_offline = 6;
    string id_cancel = 7;

}

message CheckRequest {
    bytes rro_fn_sign = 3;
}
message CheckRequestId {
    string id = 1;
    bytes rro_fn_sign = 2;
}

message CheckResponse {
    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;
        ERROR_OFFLINE_168 = -11;
        ERROR_BAD_HASH_PREV = -12;
        ERROR_NOT_REGISTERED_RRO = -13;
        ERROR_NOT_REGISTERED_SIGNER = -14;
        ERROR_NOT_OPEN_SHIFT = -15;
        ERROR_OFFLINE_ID = -16;
    }
    Status status = 2;
    bytes id_sign = 3;
    bytes data_sign = 4;
    string error_message = 5;
}
message StatusResponse {
    bool open_shift = 1;
    bool online = 2;
    string last_signer = 3;
    enum Status {
        UNKNOWN = 0;
        OK = 1;
        ERROR_VEREFY = -1;
        ERROR_CHECK = -2;
        ERROR_UNKNOWN = -4;
        ERROR_NOT_REGISTERED_RRO = -13;
        ERROR_NOT_REGISTERED_SIGNER = -14;
    }
    Status status = 4;
    string error_message = 5;
}

message RroInfoResponse {
    enum Status {
        UNKNOWN = 0;
        OK = 1;
        ERROR_VEREFY = -1;
        ERROR_CHECK = -2;
        ERROR_UNKNOWN = -4;
        ERROR_NOT_REGISTERED_RRO = -13;
        ERROR_NOT_REGISTERED_SIGNER = -14;
    }
    Status status = 1; // Статус відповіді
    int32 status_rro = 2; // Статус ПРРО
    bool open_shift = 3; // Статус зміни
    bool online = 4; // Стан ПРРО
    string last_signer = 5; // Останній підписант
    string name = 6; // Назва
    string name_to = 7; // Назва ТО
    string addr = 8; // Адреса ТО
    bool single_tax = 9; // Платник єдиного податку
    bool offline_allowed = 10; // Дозволено роботу в офлайн режимі
    int32 add_num = 11; // Додаткова кількисть офлайн номерів
    string pn = 12; // Податковий номер платника ПДВ

    message Operator {
        string serial = 1; // publicKeyId
        int32 status = 2; // Статус
        bool senior = 3; // Старший касир
        string isname = 4; // ПІБ
    }
    repeated Operator operators = 13; // Касири
    string tins = 14; // Податковий номер платника
    int32 lnum = 15; // Локальний номер каси
    string name_pay = 16; // Назва платника
}


service ChkIncomeService {
    rpc sendChk (Check) returns (CheckResponse);
    rpc sendChkV2 (Check) returns (CheckResponse);
    rpc lastChk (CheckRequest) returns (CheckResponse);
    rpc ping (Check) returns (CheckResponse);
    rpc delLastChk (CheckRequest) returns (CheckResponse);
    rpc delLastChkId (CheckRequestId) returns (CheckResponse);
    rpc statusRro (CheckRequest) returns (StatusResponse);
    rpc infoRro (CheckRequest) returns (RroInfoResponse);
}

3. Коди підтверджень та помилок

Код Назва   Використання
0   Unknown не визначений
1   OK      Чек фіскалізовано, надано номер
-1  ERROR_VEREFY    помилка перевірки підпису
-2  ERROR_CHECK     помилка перевірки РРО
-3  ERROR_SAVE      помилка запису
-4  ERROR_UNKNOWN   загальна помилка
-5  ERROR_TYPE      помилка типу посилки
-6  ERROR_NOT_PREV_ZREPORT  нема Z-звіту за попередній день
-7  ERROR_XML       невірний формат XML ( структура , фіскальний номер)
-8  ERROR_XML_DATE  невірний формат XML дата не відповідає Check.date
-9  ERROR_XML_CHK   невірний формат XML чеку
-10 ERROR_XML_ZREPORT       невірний формат Z-звіту
-11 ERROR_OFFLINE_168       РРО заблокований, перевищено ліміт 168 годин офлайну
-12 ERROR_BAD_HASH_PREV     Невірний хеш попереднього чеку
-13 ERROR_NOT_REGISTERED_RRO        не зареєстровано ПРРО
-14 ERROR_NOT_REGISTERED_SIGNER     не зареєстрований підписант
-15 ERROR_NOT_OPEN_SHIFT    не відкрита зміна
-16 ERROR_OFFLINE_ID        невірний оффлайн ID

Додатковий  опис помилок:

    ERROR_CHECK errorMessage:
    •       shift is already open – зміна вже відкрита
    •       this key opens a shift on another device fn – цим підписом відкрита зміна на іншому ПРРО
    •       there can be only one signatory within a shift – у зміні може бути лише один підписант
    •       there can be only one signatory within a shift, shift closing can be a senior – у зміні може бути лише один підписант, закриття зміни може бути здійснене старшим касиром.
    •       Permitted to use only after 2021-10-01 – можливо використовувати тільки з 01.10. 2021

    ERROR_SAVE errorMessage:
    •       incorrect hash – Невірний хеш попереднього чеку, або дубль чека
    ERROR_XML_ZREPORT errorMessage :
    •       not correct teg Z - Невірний xml Z-звіту

4 Зміни формату чеків

Попередження

До 01.10.2021 для службових чеків, які надходять на АРІ ФСКО ЕК метод rpc sendChk (Check) returns (CheckResponse)

  • службовий чек відкриття зміни Т=8;
  • службовий чек переходу в режим офлайн Т=9;
  • службовий чек переходу в режим онлайн Т=10;
  • службовий чек перевірки доступності ПРРО в режимі онлайн Т=11;
  • службовий чек запиту діапазону резервних номерів для роботи в режимі офлайн Т=12.

Попередження

З 01.10.2021 для службових чеків, які надходять на АРІ ФСКО ЕК та формуються програмними РРО перекодувати типи чеків метод rpc sendChkV2 (Check) returns (CheckResponse)

  • службовий чек відкриття зміни з Т=8 на Т=108;
  • службовий чек переходу в режим офлайн з Т=9 на Т=109;
  • службовий чек переходу в режим онлайн з Т=10 на Т=110;
  • службовий чек перевірки доступності ПРРО в режимі онлайн з Т=11 на Т=111;
  • службовий чек запиту діапазону резервних номерів для роботи в режимі офлайн з Т=12 на Т=112.

5 Перевірка чеку:

Для перевірки чеку можна використовувати адресу https://cabinet.tax.gov.ua/cashregs/check

Або прямий виклик https://cabinet.tax.gov.ua/cashregs/check?id=wuBKGM848z4&date=20210201 де wuBKGM848z4 – ід чеку , 20210201 дата чеку в форматі yyyyMMdd.

Також це посилання можна використовувати в QR Code

_images/qr.png