Перейти до вмісту

API-ключі

API-ключ дозволяє вашому бекенду працювати з одним магазином. Створіть його в кабінеті, збережіть на своєму сервері й надсилайте як bearer-токен.

У магазині створіть ключ з правами read і write. Токен ivk_ показується один раз; збережіть його одразу. У магазину може бути до 10 невідкликаних ключів; див. Ліміти.

Агент може створити той самий ключ за допомогою своєї сесії входу:

Terminal window
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, керування ключами може вимагати свіжого другого фактора.

Terminal window
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. Ніколи не розміщуйте його в коді браузера, URL оплати чи спільному чаті.

Архівування магазину вимикає всі його ключі.

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. Порожній список знімає обмеження.

Оновлення або відкликання

Section titled “Оновлення або відкликання”

Створіть ключ-заміну, оновіть свій бекенд, а потім відкличте старий ключ через DELETE /api/v1/shops/{shop_id}/keys/{key_id}.

PATCH за тим самим шляхом може змінити name, enabled, scopes або allowed_ips. Пропущені поля залишаються без змін. Редагування не розкриває й не оновлює токен.

Ключі працюють, поки їх не вимкнено або не відкликано, з урахуванням доступу до облікового запису й магазину. Це не обіцянка постійного доступу. Деталі запитів див. у довіднику API.