API hutkoВерсия 1.0

Схема роботи програмного РРО

1. Торговець реєструє ПРРО в ДПС через подання форми J/F1316603.
2. Торговець реєструє всіх касирів шляхом подання форми J/F1391802.
3. Торговець реєструється в особистому кабінеті Hutko. Ми його називаємо мерчант-портал. Тут же потрібно завантажити ключі ПРРО. Про те, як їх отримати, описано нижче.
4. З мерчант-порталу ключі завантажуються в модуль ПРРО, в якому автоматично активується онлайн-каса Hutko.
5. Модуль програмного РРО, своєю чергою, отримує від ДПС реєстраційні дані касира, ПРРО та об’єкта оподаткування і зберігає їх для подальшої фіскалізації покупок.
6. У процесі покупки покупець переходить на сторінку з товаром або послугою інтернет-торговця.
7. Сайт інтернет-магазину формує класичний кошик для покупця (якщо кошика немає, то достатньо опису товару або послуги за умови, що це одна номенклатура).
8. Інформація про кошик/товар/послугу потрапляє на платіжний шлюз Hutko. Це може бути зроблено через:
   – платіжні модулі для CMS і конструкторів сайтів;
   – виставлення онлайн-інвойсу за допомогою мерчант-порталу Hutko;
   – платіжну кнопку або посилання, які можна створити в мерчант-порталі;
   – пряму інтеграцію с API Hutko – для простоти можна скористатися готовими SDK для вашої мови розробки або мобільного додатка.
9. Hutko формує посилання на платіжну сторінку, на яку інтернет-магазин перенаправляє покупця для введення платіжних даних банківської картки.
10. Платіжний шлюз Hutko списує з картки покупця кошти.
11. Модуль ПРРО фіскалізує на сервері ДПС чек купівлі, передаючи вміст кошика з описом товарів і послуг.
12. ПРРО надсилає чек покупцеві на email. 
13. Наприкінці дня ПРРО автоматично формує Z-звіт і закриває зміну.
14. Надалі торговець може отримати всі звіти, які підтверджують фіскалізацію і необхідні для бухгалтерії, через мерчант-портал або API.

Фіскалізація покупки

Параметри, які необхідно передавати додатково для інтеграції з протоколом програмного РРО

У запит на купівлю додається параметр reservation_data – це JSON, закодований алгоритмом BASE64, який має таку структуру:

{
 "products": [
   {
     "id": 1,
     "name": "Мигдаль жар.",
     "price": 700.00,
     "total_amount": 140.00,
     "quantity": 0.2
   },
   {
     "id": 2,
     "name": "Кешью очищ.",
     "price": 850.00,
     "total_amount": 127.5,
     "quantity": 0.15
   }
 ]
}

Примітка

Якщо параметр reservation_data не передається, то чек буде сформовано з 1 одиниці товару з вартістю, зазначеною в параметрі amount та описом, зазначеним у order_desc

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

Опитування деталей фіскального запису

Запит необхідно надсилати на https://pay.hutko.org/api/get_kkt_logs методом POST

Приклад запиту (JSON)

{
  "request": {
    "order_id": "13731336126512",
    "merchant_id": 1700002,
    "signature": "2e4a8881c428037fdf266b18a29a282aba79ed58"
  }
}

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

Формат відповіді.

Приклад відповіді :

{
  "response": {
    "1499968937": {
      "request": {
        "CHECKPAY": [
          {
            "SUM": "80.00",
            "PAYSYS": [
              {
                "NAME": "ПЛАТІЖНА СИСТЕМА MasterCard",
                "AUTHCD": "46049Z",
                "EPZDETAILS": "444444XXXXXX1111",
                "ACQUIRETRANSID": "024046466130"
              }
            ],
            "PAYFORMCD": 1,
            "PAYFORMNM": "Електронним платіжним засобом"
          }
        ],
        "CHECKBODY": [
          {
            "CODE": 476657827,
            "COST": "80.00",
            "NAME": "Заказ №",
            "PRICE": "80.00",
            "VALCD": "980",
            "VALNM": "грн.",
            "AMOUNT": 1,
            "UNITNM": "од.",
            "VALSYMCD": "UAH",
            "DESCRIPTION": "desc"
          }
        ],
        "CHECKHEAD": {
          "TIN": "3263608852",
          "UID": "0E9B042D-888D-452C-B36B-12F283B76B02",
          "VER": 1,
          "ORGNM": "ТЕСТОВИЙ ПЛАТНИК",
          "CASHIER": "Тестовий платник",
          "DOCTYPE": 0,
          "LOGOURL": "https://logo.io/uploads/2021/logo.png",
          "OFFLINE": "false",
          "POINTNM": "ФОП Тестовий",
          "ORDERNUM": 4765,
          "ORDERDATE": "28122021",
          "ORDERTIME": "103735",
          "POINTADDR": "УКРАЇНА, ТЕРНОПIЛЬСЬКА ОБЛ., М. ТЕРНОПІЛЬ, м.Тернопіль, вул.Корольова,7/185",
          "DOCSUBTYPE": 0,
          "CASHDESKNUM": 1,
          "CASHREGISTERNUM": 4000000000
        },
        "CHECKTOTAL": {
          "SUM": 80,
          "RNDSUM": "0.00",
          "NORNDSUM": 80,
          "NOTAXSUM": 80
        }
      },
      "response": {
        "UID": "0E9B042D-888D-452C-B36B-12F283B76B02",
        "VER": "1",
        "ORDERNUM": "4765",
        "ERRORCODE": "0",
        "ORDERDATE": "28122021",
        "ORDERTIME": "103717",
        "ORDERTAXNUM": "123456789"
      },
      "type": "purchase"
    },
    "response_status": "success"
  }
}

Отримання графічної версії фіскального чека купівлі

Запит необхідно надсилати на https://pay.hutko.org/kkt/ereceipt/check методом POST

Приклад запиту (JSON)

{
  "request": {
    "transaction_id": "1499968937",
    "merchant_id": 1700002,
    "receipt_type": "receipt",
    "signature": "2e4a8881c428037fdf266b18a29a282aba79ed58"
  }
}

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

"tran_type": "purchase" або "reverse" або "capture"

"receipt" або "zreport"

Приклад відповіді:

{
  "check_url": "https://merchportal-ereceipt.s3.amazonaws.com/ereceipt/check_1499968937.pdf?AWSAccessKeyId=YYYYYYYYYYYYYYYYYYYYYY&Signature=XXXXXXXXXXXXXXXXXXXXXXXX%3D&Expires=1956257837"
}