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

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

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

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

Это удобно, когда у вас несколько торговых точек, несколько брендов в одном юрлице или вы хотите видеть отчётность по менеджерам и каналам продаж.

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

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

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

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

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

• У счёта есть поле api_key_id — ссылка на ключ-создатель; по нему и заполняется «Источник».
• Вебхуки маршрутизируются per-key — до двух получателей на событие: (1) ключ, которым создан счёт (если активен и с адресом), и (2) ключ по умолчанию организации (is_org_default), если это другой ключ. То есть точка получает событие на свой адрес, а «главный» ключ по умолчанию собирает все события организации как catch-all.
• В payload вебхука поле source — имя ключа-создателя, по нему принимающая сторона понимает точку.
• Circuit breaker — тоже per-key: если адрес одной точки перестаёт отвечать, на паузу встаёт только её доставка (5 неудач → 5 минут, 10 → 30 минут, 20 → 2 часа, 50 → полное отключение), остальные точки не затрагиваются. Подробнее — в статье про вебхуки.

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

Это важная часть — чтобы вы не ждали от разделения по ключам того, чего оно пока не даёт:

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

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

Кому это подходит

• Несколько торговых точек одного юрлица — учёт и уведомления по каждой точке, деньги на общий счёт.
• Мультибренд в одном юрлице — по ключу на бренд, у каждого свой адрес уведомлений (паттерн «2 ключа + 2 вебхука»). Для продаж через Telegram-ботов и мини-приложения — «ApiPay для Telegram-бота».
• Отчётность по менеджерам или каналам — ключ на канал (сайт, бот, офлайн), считаете счета по каждому.
• Платформы и SaaS, которые ведут несколько клиентов.

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

• Ждать, что деньги точек придут раздельно. Нет — все на один Kaspi-счёт организации. Разделяется учёт, не деньги.
• Пытаться выгрузить экспорт по одной точке. Экспорт игнорирует фильтр «Источник» и отдаёт все счета организации.
• Полагать, что тариф или лимит будет на точку. Тариф и лимиты — общие на организацию.
• Не видеть колонку «Источник» и решить, что её нет. На узком экране включите её через кнопку «Колонки».
• Выставлять счета всех точек одним ключом. Тогда «Источник» у всех одинаковый и разреза не будет — используйте ключ каждой точки.

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