Коды ошибок и решения

Ошибка −1

Текст: Request https://devkkm.webkassa.kz/api/v4/XReport response with error: code −1 — Неправильная попытка отправки повторного запроса. Порядковый номер запроса и токен имеют те же значения, что и в предыдущем запросе, но код команды отличается.

Решение: тестовая касса на протоколе 2.0.2. Рекомендуем создать новую кассу через кабинет интегратора и работать на ней.

Ошибка 2 — Срок действия сессии истёк

• Используется старый токен после получения нового → выполнить запрос на получение нового токена: POST /api/v4/Authorize.
• Истекла лицензия кассы (см. Ошибка 10).
• Интегратор не реализовал обновление токена при ошибке авторизации и 1 раз в 24 часа.
• Одна учётная запись сотрудника используется на нескольких кассах одновременно. Несколько касс могут работать под одним токеном по API; реализация синхронизации токена при получении нового — ответственность интегратора.
  

Ошибка 6 — касса не зарегистрирована

Текст: {"Errors":[{"Code":6,"Text":"Касса с заводским номером: SWKxXxXxX не зарегистрирована в системе"}]}

Решение: интегратор передаёт неверный идентификатор кассы в поле CashboxUniqueNumber — вместо ЗНК передаётся регистрационный номер кассы. Эти значения не равны и не взаимозаменяемы. В поле CashboxUniqueNumber всегда должен передаваться Заводской Номер Кассы (ЗНК), например SWK000112233.

Ошибка 8 — недостаточно наличности

Текст: {"Errors":[{"Code":8,"Text":"В кассе недостаточно наличности для проведения операции (В кассе: 38,700.000)"}]}

Решение: в кассе отсутствуют наличные для операции. Доработать ПО, чтобы проверка разницы изымаемых средств предварительно проходила локально; добавить средства в кассу запросом POST /api/v4/MoneyOperation.

Ошибка 9

• 9-1. "Некорректно реализована интеграция. Запросы по кассе должны отправляться последовательно…" → доработать ПО, чтобы новый запрос по каждой отдельной кассе нельзя было отправить до получения ответа на предыдущий или таймаута.
• 9-2. "Поле не является корректным email адресом" → реализовать проверку e-mail на стороне ПО на соответствие шаблону.
• 9-3. "Сумма чека N больше суммы платежей X" → реализовать проверку платежей на стороне ПО (нередки ошибки с типами данных).  Price - размер возвращаемой суммы для каждой конкретной позиции (из решения кассира). Payments - сумма возврата по всем позициям (из сумм позиций в запросе на возврат). Total - общая сумма (из чека-основания продажи).
• 9-4. "Необходимо заполнить данные чека основания" → некорректно заполнен блок ReturnBasisDetails. Версия протокола кассы для возвратов — не ниже 2.0.3, секцию ReturnBasisDetails нужно заполнять. ExternalCheckNumber не должен быть тем же, что в чеке-основании.
• 9-5. "Позиция '...': Налог подсчитан неверно. (Текущее: 3120, Ожидалось: 2689.66)" → если стоимость 19500, то 19500 × 16 / 116 = 2689,65517; после математического округления (0~4=0, 5~9=10) до 2 знаков = 2689,66. Доработать ПО, чтобы использовало эту формулу. Также округляются количество товара (до 3 знаков) и стоимость товара (до 2 знаков).
• 9-6. "Позиция 'Частичная оплата': ставка НДС 12% истекла или недоступна" → НДС передаётся 12% вместо 16% (например TaxPercent не указан при Tax > 0, TaxType != 0, или TaxPercent: 12). Изменить в ПО ставку на доступную из включённых в ЛК Webkassa: Программирование → Управление организацией → Профиль организации.

Ошибка 10 — касса не имеет активной лицензии

Текст: {"Errors":[{"Code":10,"Text":"Касса не имеет активной лицензии"}]}

• Причина 10-1: лицензия кассы закончилась. → В тестовой среде лицензию можно продлить самостоятельно в ЛК: devkkm.webkassa.kz → Кабинет интегратора → троеточие → «Добавить лицензию», либо создать новую кассу. В боевой среде требуется оплата лицензии через обслуживающий клиента ЦТО.
• Причина 10-2: смена не закрывалась более 24 часов. → Закрыть смену POST /api/v4/ZReport.
• Причина 10-3: токен истёк. → Получить новый токен POST /api/v4/Authorize.

Ошибка 11 — смена превышает 24 часа

Текст: {"Errors":[{"Code":11,"Text":"Продолжительность смены превышает 24 часа. Произведите закрытие смены."}]}

Решение: доработать ПО, чтобы смену обязательно закрывали раз в сутки. Рекомендуем предварительно переавторизоваться по кассе.

Ошибка 12 — смена уже закрыта

Текст: {"Errors":[{"Code":12,"Text":"Смена уже закрыта"}]}

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

Ошибка 14 — дубликат внешнего номера чека

Текст: {"Errors":[{"Code":14,"Text":"Чек с внешним номером xxxxxxxxxxxxxx уже присутствует в системе."}]}

Решение: настроить на стороне ПО уникальность передаваемых внешних номеров чеков для любых операций по новым чекам.