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

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

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

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

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

• report-controller: incomingReport

Правила формування та іменування 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

Відповіді

Приймає - application/json

Повертає - application/json за тим же шляхом

1.2. Надсилання архіву зі звітами (пакету) за допомогою REST АРІ

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

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

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

• report-controller: incomingReportZip

Параметри

Відповіді

Приймає - application/json

Повертає - application/json за тим же шляхом

1.3. Отримання квитанцій за допомогою REST АРІ

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

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

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

• report-controller: ІncomingReport

Відповіді

Приймає - application/json

Повертає - application/json за тим же шляхом

1.4. Визначення

InReportDao

InReportDao

ReturnKvt

ReturnKvt

ReturnReport

ReturnReport

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

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

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

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

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

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

Для всіх операцій, в тому числі для відкриття зміни, відправлення чеку,відправлення Z-звіту (в онлайні і в офлайні), запиту додаткових фіскальних номерів, а також для повідомлень про перехід в офлайн та про перехід в онлайн використовується метод «sendChk», з повідомленням «Check» та відповіддю «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);
    }

    Код Назва   Використання
    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-звіту

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

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

Або прямий виклик

https://cabinet.tax.gov.ua/cashregs/check?mac=001A000005F00000000015001146D50002924A03E61CA20AF7C297A2D6&date=20220904&time=1130&id=45&sm=780.00&fn=3000898168

де:

001A000005F00000000015001146D50002924A03E61CA20AF7C297A2D6 - MAC (hash)

45 – ід чеку

20210201 - дата чеку в форматі yyyyMMdd

1130 - час у форматі HHmm.

780.00 - сума розрахункової операції (роздільник ".")

3000898168 - фіскальний номер РРО/ПРРО, на якому він сформований

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