Коротко
Если в организации несколько кассиров Kaspi, каждый API-ключ можно привязать к конкретному кассиру. Тогда боевые счета, созданные этим ключом, идут только через него и не переходят на другого кассира, а сам ключ вообще не видит счетов чужого кассира — на них он отвечает 404.
Нужно это для двух вещей: разделить проекты между собой и получать раздельную отчётность по точкам.
Привязка выбирается из списка «Кассир» при создании ключа в разделе Интеграции кабинета.
Когда это нужно
| Ситуация | Нужна ли привязка |
|---|---|
| Одна организация, один кассир, один сайт | Нет |
| Одна организация, два сайта, два кассира | Да, каждому сайту свой ключ и свой кассир |
| Одна организация, несколько офлайн-точек | Да, отчётность разделится по точкам |
| Маркетплейс: у каждого продавца свой кассир | Да |
| Работаете только в песочнице | Нет, песочница к кассиру не привязывается |
Без привязки счёт уходит через активного кассира организации, а ключ видит все боевые счета организации.
Что делает привязанный ключ
| Действие | Поведение |
|---|---|
| Создание боевого счёта | Идёт только через привязанного кассира, не переключается |
GET /api/v1/invoices | В списке только счета этого кассира |
GET /api/v1/invoices/{id} | Счёт чужого кассира — invoice_not_found, HTTP 404 |
| Возврат, отмена | Только по счетам этого кассира |
| Счета песочницы | Общие: к кассиру не привязываются, это тестовые данные организации |
| Подписка | Запоминает, через какого кассира создана |
Чужой счёт возвращается не как «запрещено», а как не найден — это сделано намеренно: ключ не должен даже знать, какие счета существуют в соседнем проекте.
Подписка тоже запоминает кассира, через которого создана. Поэтому если вы создали подписку одним ключом, а потом перевели этот ключ на другого кассира, плановые счета продолжат выставляться через прежнего.
Как привязать в кабинете
- Войдите в кабинет: https://qut.kz/app
- В разделе Kaspi убедитесь, что нужный кассир подключён. Как добавить нескольких: Несколько кассиров.
- Перейдите в раздел Интеграции и создайте новый API-ключ.
- В окне создания выберите конкретного кассира из списка «Кассир».
- Выдайте ключу нужные права:
invoices:write,invoices:read, при необходимостиrefunds:write. - Ключ показывается один раз — скопируйте и положите в секреты своего сервера.
Ключ можно позже перевести на другого кассира: в настройках этого ключа меняется выбранный кассир.
Как проверить
Правильность привязки видно одним запросом: попробуйте привязанным ключом получить счёт чужого проекта.
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'X-API-Key: qp_live_…' \
https://api.qut.kz/api/v1/invoices/inv_из_другого_проекта
# 404 — привязка работаетСвой счёт должен вернуть 200:
curl -H 'X-API-Key: qp_live_…' \
https://api.qut.kz/api/v1/invoices?limit=5Если в списке только счета нужного кассира — всё настроено верно.
Удаление кассира: connection_has_keys
Кассира, к которому привязан ключ, удалить нельзя. При попытке вернётся:
{ "error": "connection_has_keys", "message": "К кассиру привязан API-ключ" }HTTP-статус — 409. Порядок действий:
- Посмотрите в разделе Интеграции, какие ключи привязаны к этому кассиру.
- Переведите каждый ключ на другого кассира или удалите сам ключ.
- Когда ключей не останется, кассира можно удалить.
Это намеренная защита: удалив кассира, вы бы мгновенно лишили работающий сайт или приложение возможности выставлять счета.
Если кассир сменился, правильнее не удалять, а перевести ключ на нового: Кассир сменился.
Частые ошибки
| Что видите | Причина | Решение |
|---|---|---|
invoice_not_found (404), хотя счёт есть в кабинете | Ключ привязан к другому кассиру | Используйте правильный ключ или проверьте привязку |
forbidden (403) | Счёт принадлежит совсем другой организации | Проверьте, что ключ и счёт из одной организации |
connection_has_keys (409) | Пытаетесь удалить кассира с ключом | Сначала переведите ключ |
| Счёт ушёл через «не того» кассира | Ключ не привязан | Привяжите ключ к кассиру |
| В песочнице разделение не работает | Песочница к кассиру не привязывается | Это нормально, проверяйте в боевом режиме |
Полный список: Каталог ошибок, отдельно про 404: Счёт не найден.
Вопросы и ответы
Можно привязать несколько ключей к одному кассиру? Да. Например, если на точке работают и сайт, и кассовое приложение, выдайте каждому свой ключ и привяжите оба к этому кассиру.
Что будет со старыми счетами, если перевести ключ? Ничего — они продолжат идти через прежнего кассира. Перевод влияет только на новые счета.
Вебхуки тоже можно разделить? Да. Если привязать адрес вебхука к тому же ключу, каждый проект будет получать только свои события. Подробнее: Настройка вебхуков.
Что видит непривязанный ключ? Все боевые счета организации, независимо от того, через какого кассира они созданы.
Как разделить отчётность по точкам? Выдайте каждой точке отдельный ключ и привяжите его к кассиру этой точки: Раздельная отчётность по точкам.