Коротко
Почти все проблемы с плагином делятся на две группы. Счёт вообще не создаётся — дело в ключе: его нет, он скопирован с ошибкой или не соответствует режиму. Счёт создаётся, но статус заказа не меняется — не доходит вебхук: адрес неверный, закрыт или недоступен снаружи. Какая из двух — видно сразу по журналу магазина.
Скачать плагины: api.qut.kz/downloads. Инструкция по установке: api.qut.kz/docs/guide/wordpress.
Симптом → причина → решение
| Симптом | Причина | Решение |
|---|---|---|
| Способ оплаты вообще не виден на кассе | Плагин не включён или не та валюта магазина | Включите плагин, проверьте валюту |
| Кнопка «Оплатить» выдаёт ошибку | Ключа нет или он скопирован неверно | Скопируйте ключ заново, уберите пробелы |
| В тексте ошибки есть 401 | Ключ недействителен или отключён | API отвечает 401 |
| В тексте ошибки есть 403 | Не хватает scope или тариф неактивен | API отвечает 403 |
| Счёт создаётся, но покупателю не приходит | Стоит тестовый ключ | Забыли выключить тестовый режим |
| Покупатель оплатил, заказ висит в ожидании | Не доходит вебхук | Проверьте адрес вебхука |
| Часть заказов проходит, часть нет | Адрес нестабилен или мешает слой кеша | Смотрите журнал |
1. Верный ли ключ
Ключ в настройках плагина — самая частая причина.
- Скопирован целиком? Ключ начинается с
qp_live_илиqp_test_. Если обрезано начало или конец, придёт 401. - Нет ли лишнего пробела? При копировании в конец попадает пробел или перевод строки, глазами это не видно. Очистите поле и вставьте заново.
- Существует ли ключ? В кабинете он мог быть удалён или отключён.
- Хватает ли прав? Плагину нужны минимум
invoices:writeиinvoices:read, а если включены возвраты — ещёrefunds:write.
Самый быстрый способ проверить сам ключ — сделать один запрос с сервера, минуя магазин. Если он проходит, проблема не в плагине, а в том, что вписано в настройках.
2. Совпадает ли режим
Настроек две, и они должны соответствовать друг другу:
| Режим в кабинете | Ключ в плагине | Результат |
|---|---|---|
| Боевой | qp_live_… | Настоящая оплата, всё верно |
| Песочница | qp_test_… | Тест, реальные деньги не двигаются |
| Боевой | qp_test_… | Тестовые счета, покупателю ничего не приходит |
| Песочница | qp_live_… | Ошибка или неожиданное поведение |
Если боевой магазин остался в песочнице, счета создаются, заказы приходят, а денег нет. Признаки и порядок перехода: Забыли выключить тестовый режим.
3. Доступен ли адрес вебхука снаружи
Если статус заказа не меняется, причина почти всегда здесь. Плагин умеет создавать счёт, но не получает сообщение об оплате.
Что проверить:
- HTTPS и настоящий домен. В продакшене принимается только
https, IP-адреса и временные туннели — нет. - Адрес открыт без авторизации. Если на сайте стоит пароль «идут работы», Basic Auth или правило «только для авторизованных», вебхук не дойдёт.
- Не мешают ли защитные слои. Cloudflare, ModSecurity, файрвол, правила «блокировать ботов» могут отбрасывать внешний POST-запрос.
- Редиректы. 307/308 отрабатываются только на тот же самый адрес (http→https, слеш). Редирект на другой адрес не отрабатывается.
- Кеш. Полностраничный кеш не должен затрагивать адрес вебхука.
Если ваш ответ не 2xx, доставка повторяется 11 раз (пауза растёт от 10 секунд до часа). То есть при временном сбое заказы могут дойти сами чуть позже.
Полная диагностика: Вебхук не приходит.
4. Читайте журнал магазина
Журнал — источник фактов, а не догадок.
- WooCommerce: WooCommerce → Статус → Журналы. Плагин пишет свои записи туда.
- OpenCart: Отчёты → Журнал ошибок, а также PHP-лог ошибок сервера.
- В кабинете в разделе Интеграции есть журнал доставок вебхуков: что отправлено и какой ответ получен.
Сравните два журнала. Если у нас отправлено, а в магазине не принято — проблема на пути к магазину (файрвол, авторизация, кеш). Если у нас вообще не отправлено — адрес не добавлен либо не выбран нужный тип события.
Установка и инструкция
Скачивайте актуальную версию плагина или расширения: api.qut.kz/downloads. Если на сайте стоит старая версия, сначала попробуйте обновиться — часть проблем там уже закрыта.
Пошаговая установка: api.qut.kz/docs/guide/wordpress. Настройки и сопоставление статусов заказа: Плагин WooCommerce, Расширение OpenCart 4.
Вопросы и ответы
Как проверить, что плагин вообще работает? Переведите кабинет в песочницу, впишите в плагин тестовый ключ и оформите один заказ. Если счёт появился, а после симуляции оплаты статус заказа изменился — вся цепочка рабочая.
Меняется ли статус заказа после возврата? Зависит от настроек плагина. Для возвратов ключу нужно право refunds:write.
Можно ли тестировать на локальном сервере (localhost)? Счёт создать можно, но вебхук не дойдёт: на сервер без внешнего адреса сообщение не придёт. Тестируйте там, где есть публичный адрес.
Если поменять плагин, пропадут ли старые заказы? Нет. Заказы остаются в магазине, счета — у нас.
Можно ли использовать один ключ для двух магазинов? Можно, но правильнее дать каждому магазину свой ключ: тогда поломка одного не заденет другой, и отчётность проще разделить.