Авторизация магазина

Каждый запрос должен содержать в заголовках идентификатор магазина и подпись, выполненную на основе тела запроса и секретного ключа, выданного при регистрации магазина.


  Authorization: [shopId]
  X-HMAC-Signature: [signature]
  

Описание алгоритма получения подписи

Для защищенного взаимодействия магазина и KOMTET Кассы используется подпись запроса с помощью HMAC на базе хеш-функции MD5.


  # Пример на Python 3

  import hmac, hashlib

  # msg = resp.method + resp.uri + resp.body
  msg = 'GET' + 'https://kassa.komtet.ru/api/shop/v1/queues/125' + ''

  # secret - секретный ключ магазина
  signature = hmac.new(str.encode(secret), msg, digestmod=hashlib.md5).hexdigest()
  

Получение состояния очереди

Рекомендуем выполнять проверку состояния очереди перед выполнением оплаты.

Запрос:


  GET /api/shop/v1/queues/{queue_id} HTTP/1.1
  

Ответ:


  HTTP/1.1 200 OK
  Content-Type: application/json
  Authorization: shopId
  X-HMAC-Signature: Signature-sample-DEFGHIJKLMNOPQRSTUVWXYZ0123

  {
    "id": 1,
    "name": "Очередь 1",
    "state": "active"
  }
  

Постановка задачи в очередь на фискализацию

После ответа от платежной системы необходимо отправить детали чека для фискализации в заданном формате.

Обратите внимание, что общая сумма по чеку должна быть корректной и равняться стоимости всех позиций, иначе запрос будет отклонен сервером.

Запрос:


  POST /api/shop/v1/queues/{queue_id}/task HTTP/1.1
  Content-Type: application/json
  Authorization: shopId
  X-HMAC-Signature: Signature-sample-DEFGHIJKLMNOPQRSTUVWXYZ0123

  {
    "intent": "sell",
    "print": true,
    "task_id": "1737",
    "user": "user@email.com",
    "sno": 1,
    "payments": [{
        "sum": 12566.0
    }],
    "positions": [{
        "name": "Название товара 1",
        "price": 12360.0,
        "quantity": 1,
        "total": 12360.0,
        "vat": "no"
    }, {
        "name": "Название товара 2",
        "price": 206.0,
        "quantity": 1,
        "total": 206.0,
        "vat": "18"
    }]
  }
  

Ответ:


  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "id": "123",
    "external_id": "123",
    "print_queue_id": "123"
  }
  

Параметры чека

Параметр Обязательный параметр Описание
intent да Направление платежа.
Возможные значения:
  • sell - платеж
  • sellReturn - возврат
print нет Печатать чек или нет.
task_id да Номер операции в вашей системе.
user да Email пользователя для отправки электронного чека.
sno да Система налогооблажения.
Возможные значения:
  • 0 - ОСН
  • 1 - УСН доход
  • 2 - УСН доход - расход
  • 3 - ЕНВД
  • 4 - ЕСН
  • 5 - Патент
payments[].sum да Общая сумма по чеку.
positions[].name Да Наименование позиции в чеке.
positions[].price Да Цена позиции в чеке.
positions[].quantity Да Количество единиц данного типа.
positions[].total Да Общая стоимость позиции в чеке.
positions[].discount нет Сумма скидки в рублях.
positions[].vat да Ставка налога.
Возможные значения:
  • "0" - НДС 0%
  • "10" - НДС 10%
  • "18" - НДС 18%
  • "no" - Без НДС
  • "110" - НДС 10/110
  • "118" - НДС 18/118

Для оформления возврата используйте этот же метод с параметром intent: "sellReturn".

Отчеты после фискализации чека

После попытки фискализации будет выполнено обращение к вашему сайту по ссылкам, указанным при регистрации.

Все запросы подписаны следующим образом:

signature = hmac.new(shop.secret, 'POST' + url + request_body, digestmod=hashlib.md5).hexdigest()
Подтверждение успешной фискализации чека:

Запрос:


  POST {SuccessURL} HTTP/1.1
  X-HMAC-Signature: signature
  Content-Type: application/json

  {
    "id": 123,
    "external_id": "12356",
    "state": "done",
    "fiscal_data": {
      "t": "20170810T1616",
      "s": "406.00",
      "fn": "9999078900006101",
      "i": "10",
      "fp": "2456961915",
      "n": 1
    }
  }
  

Ответ:


  HTTP/1.1 200 OK
  
Отчет об ошибке фискализации:

Запрос:


  POST {FailureURL} HTTP/1.1
  X-HMAC-Signature: signature
  Content-Type: application/json

  {
    "id": 123,
    "external_id": "12356",
    "state": "error",
    "error_description": 'Paper not found'
  }
  

Ответ:


  HTTP/1.1 200 OK
  

Параметры отчета

Параметр Описание
id Идентификатор операции в сервисе КОМТЕТ Касса.
external_id Идентификатор операции в вашей системе.
state Состояние.
Возможные значения:
  • done - успешное выполнение
  • error - ошибка фискализации
error_description Описание возникшей ошибки.
fiscal_data.t Время фискализации чека
fiscal_data.s Сумма по чеку
fiscal_data.fn Заводской номер фискального накопителя
fiscal_data.i Номер фискального документа
fiscal_data.fp Фискальный признак документа
fiscal_data.n Тип операции.
Возможные значения:
  • 1 - Приход
  • 2 - Возврат прихода