# Привязка API-ключа к кассиру

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

## Коротко

Если в организации несколько кассиров Kaspi, каждый API-ключ можно привязать **к конкретному кассиру**. Тогда боевые счета, созданные этим ключом, идут только через него и не переходят на другого кассира, а сам ключ вообще не видит счетов чужого кассира — на них он отвечает `404`.

Нужно это для двух вещей: разделить проекты между собой и получать раздельную отчётность по точкам.

Привязка выбирается из списка «Кассир» при создании ключа в разделе **Интеграции** кабинета.

## Когда это нужно

| Ситуация | Нужна ли привязка |
|---|---|
| Одна организация, один кассир, один сайт | Нет |
| Одна организация, два сайта, два кассира | Да, каждому сайту свой ключ и свой кассир |
| Одна организация, несколько офлайн-точек | Да, отчётность разделится по точкам |
| Маркетплейс: у каждого продавца свой кассир | Да |
| Работаете только в песочнице | Нет, песочница к кассиру не привязывается |

Без привязки счёт уходит через активного кассира организации, а ключ видит все боевые счета организации.

## Что делает привязанный ключ

| Действие | Поведение |
|---|---|
| Создание боевого счёта | Идёт только через привязанного кассира, не переключается |
| `GET /api/v1/invoices` | В списке только счета этого кассира |
| `GET /api/v1/invoices/{id}` | Счёт чужого кассира — `invoice_not_found`, HTTP 404 |
| Возврат, отмена | Только по счетам этого кассира |
| Счета песочницы | Общие: к кассиру не привязываются, это тестовые данные организации |
| Подписка | Запоминает, через какого кассира создана |

Чужой счёт возвращается не как «запрещено», а как **не найден** — это сделано намеренно: ключ не должен даже знать, какие счета существуют в соседнем проекте.

Подписка тоже запоминает кассира, через которого создана. Поэтому если вы создали подписку одним ключом, а потом перевели этот ключ на другого кассира, плановые счета продолжат выставляться через прежнего.

## Как привязать в кабинете

1. Войдите в кабинет: https://qut.kz/app
2. В разделе **Kaspi** убедитесь, что нужный кассир подключён. Как добавить нескольких: [Несколько кассиров](/kb/ru/two-cashiers).
3. Перейдите в раздел **Интеграции** и создайте новый API-ключ.
4. В окне создания выберите конкретного кассира из списка «Кассир».
5. Выдайте ключу нужные права: `invoices:write`, `invoices:read`, при необходимости `refunds:write`.
6. Ключ показывается **один раз** — скопируйте и положите в секреты своего сервера.

Ключ можно позже перевести на другого кассира: в настройках этого ключа меняется выбранный кассир.

## Как проверить

Правильность привязки видно одним запросом: попробуйте привязанным ключом получить счёт чужого проекта.

```bash
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:

```bash
curl -H 'X-API-Key: qp_live_…' \
  https://api.qut.kz/api/v1/invoices?limit=5
```

Если в списке только счета нужного кассира — всё настроено верно.

## Удаление кассира: connection_has_keys

Кассира, к которому привязан ключ, удалить нельзя. При попытке вернётся:

```json
{ "error": "connection_has_keys", "message": "К кассиру привязан API-ключ" }
```

HTTP-статус — 409. Порядок действий:

1. Посмотрите в разделе **Интеграции**, какие ключи привязаны к этому кассиру.
2. Переведите каждый ключ на другого кассира или удалите сам ключ.
3. Когда ключей не останется, кассира можно удалить.

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

Если кассир сменился, правильнее не удалять, а перевести ключ на нового: [Кассир сменился](/kb/ru/change-cashier).

## Частые ошибки

| Что видите | Причина | Решение |
|---|---|---|
| `invoice_not_found` (404), хотя счёт есть в кабинете | Ключ привязан к другому кассиру | Используйте правильный ключ или проверьте привязку |
| `forbidden` (403) | Счёт принадлежит совсем другой организации | Проверьте, что ключ и счёт из одной организации |
| `connection_has_keys` (409) | Пытаетесь удалить кассира с ключом | Сначала переведите ключ |
| Счёт ушёл через «не того» кассира | Ключ не привязан | Привяжите ключ к кассиру |
| В песочнице разделение не работает | Песочница к кассиру не привязывается | Это нормально, проверяйте в боевом режиме |

Полный список: [Каталог ошибок](/kb/ru/error-catalog), отдельно про 404: [Счёт не найден](/kb/ru/invoice-not-found).

## Вопросы и ответы

**Можно привязать несколько ключей к одному кассиру?** Да. Например, если на точке работают и сайт, и кассовое приложение, выдайте каждому свой ключ и привяжите оба к этому кассиру.

**Что будет со старыми счетами, если перевести ключ?** Ничего — они продолжат идти через прежнего кассира. Перевод влияет только на новые счета.

**Вебхуки тоже можно разделить?** Да. Если привязать адрес вебхука к тому же ключу, каждый проект будет получать только свои события. Подробнее: [Настройка вебхуков](/kb/ru/webhook-setup).

**Что видит непривязанный ключ?** Все боевые счета организации, независимо от того, через какого кассира они созданы.

**Как разделить отчётность по точкам?** Выдайте каждой точке отдельный ключ и привяжите его к кассиру этой точки: [Раздельная отчётность по точкам](/kb/ru/multi-point-reporting).