Открытый API для кассовых систем

Общие правила

Сессия и согласие клиента

• Согласие клиента — на каждый чек: QR или шесть цифр с экрана клиента открывают сессию, она проводит один чек и живёт 2 часа, у ключа кассы — 12 часов. Следующий чек — новый QR.
• QR и код одноразовые: posIdentify гасит их, как скан кассира. Повтор того же запроса тем же ключом (ответ не дошёл) отдаёт ту же сессию — пока по ней не проведён чек и она не истекла; кассе Unemi и другому ключу — code_used.
• У ключа кассы тот же код или номер телефона в пределах 12 часов отдаёт ту же открытую сессию и после того, как сам код устарел (живёт около минуты): касса спрашивает карту клиента несколько раз за заказ. Свежий код другого клиента с теми же цифрами важнее — он гасится и открывает новую сессию.
• Чек отменили (posUndo) — согласие на него не израсходовано: та же сессия, пока жива, проводит его заново.
• По номеру телефона находятся только клиенты этого заведения (у них уже есть карта, бонусный счёт или абонемент), а сессия — только для начислений: accrualOnly: true, штампы и бонусы без списания.
• Номер ничем не подтверждён: списать бонусы, оформить или выдать абонемент, погасить награду можно только по QR или коду с телефона клиента — иначе consent_required. Нового клиента по номеру API не заводит.

Повторы и идемпотентность

• Ответ не дошёл — повторите тот же запрос: второй раз операция не проводится.
• posIdentify с тем же QR или кодом от того же ключа отдаёт ту же сессию, пока по ней не проведён чек и она не истекла.
• posApply с тем же receiptId и теми же данными отдаёт сохранённый ответ с replayed: true — без второй операции и второго пуша клиенту. Тот же receiptId с другими данными или по другой сессии — receipt_conflict. Кассир и позиции (cashier, items) — справка: в сравнение не входят.
• receiptId уникален в пределах точки: если на точке несколько касс, их номера чеков не должны совпадать — например, с префиксом кассы. После отмены (posUndo) тот же receiptId можно провести заново.
• Повтор posUndo отдаёт тот же ответ с replayed: true.
• rate_limited и too_many_attempts — подождите details.seconds секунд; internal — повторите позже.

Ответ с ошибкой

Ошибка — HTTP-статус и тело:

{
  "error": {
    "code": "cooldown",
    "message": "Слишком рано: следующий штамп можно через 12 мин",
    "details": { "minutes": 12 },
    "requestId": "Qk2v9XyZaB7cD1eF3gH5"
  }
}

Касса смотрит на error.code — коды стабильны (таблицы ниже). message — по-русски, как в кассе Unemi; details — числа к коду (минуты, лимит, баланс).

Коды ошибок

Доступ и запрос

Узнавание (posIdentify)

Чек (posApply)

Отмена (posUndo)

Безопасность и данные

• Ключ — unemi_<id ключа, 20 знаков>_<секрет, 48 hex>, 192 случайных бита секрета. Unemi хранит только sha256 секрета и последние четыре знака для узнавания в списке; неверный, кривой и несуществующий ключ — один ответ unauthorized.
• Чужое заведение недоступно: ключ привязан к заведению, сессия и чек ищутся только в нём; ключ точки видит только свою точку. Чужие сессия, программа, награда и чек отвечают «не найдено».
• Персональные данные: касса получает имя клиента (как кассир Unemi Staff), балансы, награды и уровень. Телефона, почты и внутреннего id Unemi в ответах нет; id клиента — отдельный псевдоним для каждого заведения.
• Перебор кодов и номеров: промахи узнавания (code_not_found, customer_not_found) копятся на ключ 15 минут; после 5 — пауза 1 минута, после 10 — 5 минут, после 15 — 30 минут (too_many_attempts). Проводить и отменять чеки пауза не мешает.
• Журнал запросов в кабинете — без данных клиента, хранится 30 дней.
• Песочницы нет: интеграцию проверяют на тестовом заведении на тарифе Pro.

Ключ кассы

• Ключ кассы — ключ API одной точки, отмеченный кассовой системой: r_keeper, iiko, Syrve или своя касса сети. Создаёт владелец в кабинете: «API и интеграции» → «Создать ключ» → «Касса r_keeper». Ключа кассы на всё заведение нет: касса стоит в конкретной точке.
• У ключа — правила точки: программа по умолчанию и действие (штамп — для штамп-карты, бонусы — для бонусной карты), порог суммы (0 … 10 000 000 ₸) и коды товаров кассы (до 100, каждый до 40 знаков без пробелов), — и язык текстов на экране кассы, один из шести языков Unemi. Правила и язык меняются без нового ключа; для другой кассы создают новый ключ.
• Что иначе в методах: сессия живёт 12 часов, и тот же код или номер в заказе отдаёт ту же сессию; posIdentify отдаёт defaultProgram; чек без программы проходит по программе по умолчанию, а если ничего не начислено — причина в skipped.
• Цифровой QR: пока у заведения есть действующий ключ кассы r_keeper, в QR карты клиента — те же шесть цифр, что под ним: сканер r_keeper читает их как номер карты. В posIdentify их передают в qr (identifiedBy: "qr"). Общий QR из меню приложения (без карты) остаётся обычным: клиент называет шесть цифр под ним.

{
  "name": "r_keeper · Абая",
  "venueId": "v8Kp2LmQx1",
  "pos": {
    "system": "r_keeper",
    "language": "ru",
    "rules": {
      "programId": "q2Nw7xRt",
      "action": "bonus",
      "minAmount": 0,
      "productCodes": []
    }
  }
}

Мост r_keeper для дилеров Скоро

Модуль HttpFarCard (ExtDllHTTP.dll) кассового сервера r_keeper сам шлёт POST с XML — запрос карты (getcardinfoex) и проводки закрытого чека (transactionsex), — а мост posRkeeper проводит их тем же ядром, что и методы выше: узнаёт клиента, проводит чек, отменяет его при откате и возврате.

Проводки отклоняются, только когда нельзя принять оплату бонусами (например, не хватает бонусов, клиент назван по телефону или нет бонусной программы): чек без оплаты бонусами касса закрывает всегда, а если начисление не прошло, причину владелец видит в журнале запросов.

Откат оплаты, возврат и откат возврата кассу не останавливают: возврат отменяет чек в пределах 48 часов, а что Unemi не отменил, владелец видит в журнале возвратов. Подарки и купоны через r_keeper не гасятся — их выдают в кассе Unemi. Тексты на экране кассы — на языке ключа.