Как разделить счета по точкам в одной организации?

Что даёт разделение по ключам

К API-ключу привязаны имя, свой адрес уведомлений (webhook_url) и свой секрет подписи, а каждый счёт запоминает, каким ключом он выставлен. Из этого складывается разрез по точкам:

• колонка «Источник» у счёта — имя ключа-создателя (например, «Точка на Абая») или «Основной», если счёт создан из кабинета;
• счётчик «Счетов создано: N» у каждого ключа в списке ключей;
• каждая точка шлёт вебхуки на свой адрес — события по её счетам и возвратам летят в её систему, лист или бота.

Как настроить: пошагово

1. Откройте «Настройки» → «Подключение» (вкладка видна роли developer и выше).
2. Нажмите «Создать новый ключ».
3. На шаге «Название» задайте имя ключа = имя точки (до 50 символов): «Точка на Абая», «Магазин на Достык», «Instagram-бот».
4. На шаге «Куда сообщать об оплате» укажите свой адрес уведомлений (webhook URL) для этой точки — тогда её события пойдут в её систему. Секрет подписи ApiPay создаст автоматически. Ключ и секрет показываются один раз — сохраните их сразу: восстановить их нельзя, потерянные придётся перегенерировать, и доставка на адрес точки прервётся.
5. Настройте так по ключу на каждую точку.
6. Выставляйте счета каждой точки её ключом (в заголовке X-API-Key).
7. Смотрите отчёт: в разделе «Счета» ориентируйтесь на колонку «Источник», а в списке ключей — на счётчик «Счетов создано» по каждой точке.

Важно: колонка «Источник» на десктопе показывается только на широких экранах; если её не видно, включите её вручную через кнопку «Колонки» над таблицей. На мобильном «Источник» показывается в карточке счёта, если он создан по ключу.

Что такое ключ и секрет и когда они перегенерируются — в статье «Чем API-ключ отличается от вебхук-секрета». Как настроить и проверить сами вебхуки — «Как настроить вебхуки ApiPay».

Как это работает под капотом (трек D)

• У счёта есть поле api_key_id — ссылка на ключ-создатель; по нему и заполняется «Источник».
• Per-key маршрутизируются события счетов, возвратов, QR-возвратов и подписок — до двух получателей на событие: (1) ключ, которым создан счёт (если активен и с адресом), и (2) ключ по умолчанию организации (is_org_default), если это другой ключ. Точка получает событие на свой адрес, а ключ по умолчанию собирает все события организации как catch-all. Дедуп здесь идёт по id ключа, а не по URL: два ключа с одинаковым адресом получат два POST'а.
• События каталога (catalog.*) и фискальных чеков (receipt.*) разреза по точкам не имеют — они уходят веером на все активные ключи организации с адресом (дедуп по URL). Не стройте на них логику «пришло на этот адрес — значит, это моя точка».
• В payload вебхука поле source — имя ключа-создателя, по нему принимающая сторона понимает точку.
• Circuit breaker — тоже per-key: если адрес одной точки перестаёт отвечать, на паузу встаёт только её доставка, остальные точки не затрагиваются. Пороги и длительности пауз — в статье Как настроить вебхуки ApiPay.

Честные ограничения

1. Отчёт по одной точке файлом пока не собрать. Фильтр «Источник» в списке счетов отбор не выполняет, а экспорт (Excel/CSV/PDF) выгружает все счета организации без разреза по точке. Разрез смотрите в самом списке — по колонке «Источник» и по счётчику «Счетов создано» у каждого ключа.
2. Деньги не разделяются — оплаты всех точек приходят на один Kaspi-счёт организации.
3. Тариф и дневные лимиты счетов — общие на всю организацию, а не на точку.

Если нужно разделить деньги, тариф и списки счетов по-настоящему — это уже отдельные организации: у каждой свой тариф, свой Kaspi-вход, свой независимый список «Счета» и свои деньги. Об этом — в статье «Несколько организаций и партнёрам».

Частые вопросы