Перейти к содержимому

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, может потребоваться свежее подтверждение.

Окно терминала
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 в путях магазина; список мерчантов для этого не нужен.

При создании или изменении ключа можно указать 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.