Перейти до основного вмісту

Додавання нового ключа​

Запит виконується методом POST у json або urlencoded форматі.

URI: /api/v1/key

Підтримуються два типи ключів: file (файловий) та cloud (хмарний).

Параметри запиту​

Ім'яТипОбов'язковийОпис
typestringНіТип ключа:
  • file — файловий (за замовчуванням)
  • cloud — хмарний
  • Якщо параметр не передано — вважається file
    keystringТак, для fileШлях до файлу ключа. Для хмарного ключа не передається
    publisherstringТакВидавець ключа. Назва має точно збігатися з назвою АЦСК зі списку, підтримуваного SmartSign (з урахуванням регістру та лапок), наприклад КНЕДП ДПС, КНЕДП АЦСК АТ КБ "ПРИВАТБАНК".
    Для файлового ключа (type = "file") можна вказати будь-якого видавця з цього списку.
    Для хмарного ключа (type = "cloud") необхідно обрати одного з підтримуваних надавачів:
    – КНЕДП ТОВ "Вчасно Сервіс"
    – КНЕДП ТОВ "АМО ФІНТЕХ"
    – КНЕДП "eSign" ТОВ "Ілайф"
    passstringТакПароль до ключа
    commentstringНіКоментар до ключа (наприклад, ідентифікатор аптеки). Відображається в SmartSign і повертається в списку ключів (поле COMMENT)
    drfostringХоча б одне з трьох, для ІлайфРНОКПП (код ДРФО) власника ключа. Основний параметр пошуку ключа
    edrpoustringХоча б одне з трьох, для ІлайфКод ЄДРПОУ організації. Уточнює вибір ключа, якщо в людини ключі в кількох організаціях
    serialstringХоча б одне з трьох, для ІлайфСерійний номер ключа. Дозволяє вибрати конкретний ключ (див. Особливості ключів Ілайф)
    idstringТак, для Вчасно та АМО ФІНТЕХІдентифікатор ключа в хмарному сервісі видавця. Для Вчасно — у форматі UUID, наприклад 3f2b8c1e-7d4a-4e9b-a1c2-5d6e7f809a1b
    Увага!

    Для файлового ключа (type = "file"):

    • обов'язкові key, publisher, pass
    • поля хмарного ключа (drfo, edrpou, serial, id) можна не передавати

    Для хмарного ключа (type = "cloud"):

    • обов’язкові publisher, pass і, залежно від видавця:
      • КНЕДП "eSign" ТОВ "Ілайф" — хоча б одне з полів drfo, edrpou, serial (зазвичай достатньо drfo)
      • КНЕДП ТОВ "Вчасно Сервіс" — id
      • КНЕДП ТОВ "АМО ФІНТЕХ" — id
    • поле key не передається і не використовується

    Для ключа Ілайф обов'язково передати хоча б одне з полів drfo, edrpou або serial. Зазвичай достатньо drfo. Інші поля уточнюючі: вони потрібні, якщо в людини кілька чинних ключів.

    Ілайф обирає ключ за переданими полями:

    ПереданоЯкий ключ буде використано
    лише drfoчинний ключ власника з найдовшим терміном дії
    лише serialключ із зазначеним серійним номером
    drfo + edrpouключ власника в зазначеній організації
    drfo + edrpou + serialключ, що відповідає всім трьом полям
    Коли потрібен серійний номер

    Під час перевипуску ключа в людини деякий час є два чинні ключі: старий, термін дії якого закінчується, і новий. Якщо зміну на касі відкрито старим ключем, а ключ додано лише за drfo, Ілайф обере новий ключ, бо в нього довший термін дії. Підписи підуть від іншого ключа, і чеки за відкритою зміною не пройдуть.

    Щоб цього уникнути, вкажіть serial старого ключа. Після закриття зміни вкажіть серійний номер нового ключа.

    Якщо в людини ключі в кількох організаціях, вкажіть також edrpou.

    Увага!

    Якщо передати лише edrpou, ключ може не знайтися. Передавайте edrpou разом із drfo.

    Приклад запиту для файлового ключа​

    Запит: /api/v1/key
    {
    "type": "file",
    "comment": "Аптека N1",
    "key": "c:\\test.dat",
    "publisher": "КНЕДП ДПС",
    "pass": "111"
    }

    Приклад запиту для хмарного ключа​

    КНЕДП "eSign" ТОВ "Ілайф"

    Мінімальний запит (лише drfo):

    Запит: /api/v1/key
    {
    "type": "cloud",
    "comment": "Аптека N1",
    "publisher": "КНЕДП \"eSign\" ТОВ \"Ілайф\"",
    "pass": "222222",
    "drfo": "1234567890"
    }

    Запит з уточненням ключа (edrpou та serial):

    Запит: /api/v1/key
    {
    "type": "cloud",
    "comment": "Аптека N1",
    "publisher": "КНЕДП \"eSign\" ТОВ \"Ілайф\"",
    "pass": "222222",
    "drfo": "1234567890",
    "edrpou": "21032333",
    "serial": "011555"
    }

    КНЕДП ТОВ "Вчасно Сервіс"

    Запит: /api/v1/key
    {
    "type": "cloud",
    "comment": "Аптека N1",
    "publisher": "КНЕДП ТОВ \"Вчасно Сервіс\"",
    "pass": "222222",
    "id": "3f2b8c1e-7d4a-4e9b-a1c2-5d6e7f809a1b"
    }

    КНЕДП ТОВ "АМО ФІНТЕХ"

    Запит: /api/v1/key
    {
    "type": "cloud",
    "comment": "Аптека N1",
    "publisher": "КНЕДП ТОВ \"АМО ФІНТЕХ\"",
    "pass": "222222",
    "id": "AMOKEY52345634564567"
    }

    Приклад успішної відповіді​

    Відповідь: /api/v1/key
    {
    "message": "OK"
    }

    Приклад не успішної відповіді​

    Відповідь: /api/v1/key
    {
    "message": "Відсутній файл: c:\\test.dat",
    "code": "A004"
    }

    Можливі коди помилок:

    КодОпис
    A002Не заповнено пароль (pass)
    A003Невідомий видавець ключа (publisher не знайдено в списку АЦСК)
    A004Файл ключа не знайдено за шляхом key
    A005Ключ уже додано
    A006Невідомий тип ключа (type). Допустимі: file, cloud
    A007Видавець не підтримує хмарний ключ
    A008Не заповнено обов'язковий параметр хмарного ключа: для Ілайф — жодного з drfo, edrpou, serial; для Вчасно та АМО ФІНТЕХ — id
    A009Не заповнено шлях до файлу ключа (key)
    A010Не заповнено видавця ключа (publisher)
    A011Невалідний JSON у тілі запиту

    Список видавців​

    Для хмарних ключів (type = "cloud") підтримуються лише такі АЦСК:

    • КНЕДП ТОВ "Вчасно Сервіс"
    • КНЕДП ТОВ "АМО ФІНТЕХ"
    • КНЕДП "eSign" ТОВ "Ілайф"

    Для файлових ключів (type = "file") можна використовувати будь-якого видавця зі списку АЦСК, підтримуваного SmartSign. Назву потрібно вказувати точно, як у списку (з урахуванням регістру та лапок), інакше повертається помилка A003.