API-ключи
API-ключ даёт вашему бэкенду доступ к одному магазину. Создайте его в интерфейсе, сохраните на сервере и передавайте как bearer-токен.
Создать ключ
Заголовок раздела «Создать ключ»В магазине создайте ключ с правами read и write. Токен начинается с ivk_ и показывается один раз — сохраните его сразу. У магазина может быть до 10 неотозванных ключей; см. Лимиты.
Агент может создать такой же ключ с помощью своей сессии:
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/keys' \ -H 'Authorization: Bearer <session-token>' \ -H 'Idempotency-Key: <saved-unique-key>' \ -H 'Content-Type: application/json' \ -d '{"name":"backend","scopes":["read","write"]}'Создавать и менять ключи нужно через сессию. API-ключ не может создать другой ключ. Если включено MFA, может потребоваться свежее подтверждение.
Вызвать API
Заголовок раздела «Вызвать API»curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \ -H 'Authorization: Bearer ivk_...'| Разрешение | Назначение |
|---|---|
read |
чтение инвойсов и депозитов, а также комиссий и включённых сетей мерчанта. |
write |
всё в магазине: создание, отмена и отключение инвойсов и депозитов, вебхуки, название и оформление магазина. |
Если бэкенд создаёт инвойсы и проверяет их оплату, выдайте оба права. Не считайте, что write автоматически включает read.
Ключ работает только со своим магазином, но с ним целиком. Сессия входа нужна лишь для того, куда магазин платит (получатель, делегат, место выплат), архива и сброса песочницы. С правом read он также читает комиссии и включённые сети своего мерчанта (GET /api/v1/merchants/{merchant_id}/tariffs и /networks). Всё остальное об аккаунте и мерчанте — вход, профиль, команда, другие магазины, обзор мерчанта, API-ключи, кошелёк и карта — только через сессию входа; ключ получит 403 api_key_not_allowed или 401. Не помещайте его в браузерный код, платёжную ссылку или общий чат.
Архивация магазина отключает все его ключи.
Узнать, чей ключ
Заголовок раздела «Узнать, чей ключ»GET /api/v1/me с ключом возвращает сам ключ и то, к чему он привязан:
{"user_id":"…","onboarding_required":false,"mfa_required":false,"key_id":"…","key_name":"backend","scopes":["read","write"],"shop_id":"…","shop_name":"Main shop","sandbox":false,"merchant_id":"…","merchant_name":"Acme"}Используйте shop_id в путях магазина; список мерчантов для этого не нужен.
Ограничить IP
Заголовок раздела «Ограничить IP»При создании или изменении ключа можно указать allowed_ips:
{"allowed_ips":["203.0.113.10","2001:db8::/32"]}Это примеры: замените их реальными исходящими адресами вашего бэкенда. Для одного ключа допустимо до 10 IP-адресов или CIDR-диапазонов; при большем числе придёт 400 too_many_allowed_ips. Пустой список снимает ограничение.
Заменить или отозвать
Заголовок раздела «Заменить или отозвать»Создайте новый ключ, обновите бэкенд и отзовите старый через DELETE /api/v1/shops/{shop_id}/keys/{key_id}.
PATCH по тому же пути меняет name, enabled, scopes и allowed_ips. Пропущенные поля не меняются. Редактирование не показывает токен заново и не выпускает новый.
Ключ работает, пока его не отключили или не отозвали и пока сохраняется доступ к аккаунту и магазину. Это не бессрочная гарантия доступа. Поля запросов — в справочнике API.