API-ключі
API-ключ дозволяє вашому бекенду працювати з одним магазином. Створіть його в кабінеті, збережіть на своєму сервері й надсилайте як bearer-токен.
Створіть ключ
Section titled “Створіть ключ”У магазині створіть ключ з правами 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
Section titled “Виклик 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. Ніколи не розміщуйте його в коді браузера, URL оплати чи спільному чаті.
Архівування магазину вимикає всі його ключі.
Дізнатися, чий ключ
Section titled “Дізнатися, чий ключ”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
Section titled “Обмежте доступ за IP”За бажанням вкажіть 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.