Робочий процес агента

Це шлях налаштування для агента з сесією гаманця. Якщо у вас уже є ID магазину й API-ключ, переходьте одразу до кроку 4.

Усі записи JSON нижче потребують Content-Type: application/json, bearer-токен вашої сесії та збережений Idempotency-Key, унікальний для дії.

1. Оберіть мерчанта

Прочитайте GET /api/v1/me. Якщо user.onboarding_required — true, спершу запитайте у своєї людини її адресу email, а потім завершіть налаштування:

POST /api/v1/onboarding
Content-Type: application/json

{"name":"My merchant","email":"[email protected]"}

Обліковий запис, що входив лише через гаманець, має надіслати email; без нього відповідь — 400 email_required. Неправильно сформована адреса повертає invalid_email, одноразова — disposable_email, а email, що вже належить іншому обліковому запису, — identity_already_linked. Email стає способом входу цього самого облікового запису. Invoise надсилає людині повідомлення: вона відкриває кабінет, входить цим email за одноразовим кодом і потрапляє в обліковий запис, який ви створили.

Це повертає {"completed":true}, а не ID мерчанта. Далі викличте GET /api/v1/merchants і збережіть id потрібного мерчанта.

Обліковий запис, що повертається, може належати до кількох мерчантів. Обирайте явно; не використовуйте мовчки перший запис. Не використовуйте POST /merchants для онбордингу — це повертає forbidden.

2. Створіть магазин

POST /api/v1/merchants/{merchant_id}/shops
Content-Type: application/json

{
  "name": "Agent payments",
  "sandbox": true,
  "recipient": "<your-payout-address>"
}

Збережіть повернутий id як shop_id. Для тесту почніть із пісочниці; потім створіть окремий бойовий магазин із sandbox: false.

Опціональний delegate в EVM — це гаманець розрахунків під вашим контролем. Задавайте його лише за потреби. Ніколи не використовуйте для цієї ролі адресу депозиту біржі.

Отримувача й делегата можна змінити пізніше через PATCH /api/v1/shops/{shop_id}. Уже створені рахунки й адреси зберігають ті, з якими їх створили.

Бойовий магазин натомість може платити в гаманець Invoise облікового запису: надішліть "payout_target":"wallet" без recipient. Ваша людина налаштовує цей гаманець у кабінеті; доти створення рахунку повертає 400 wallet_not_ready. Solana і Tron потребують власного отримувача; див. Solana і Tron.

3. Випустіть API-ключ магазину

Використайте свою сесію, щоб створити ключ з read і write. Збережіть повернутий токен ivk_ у своєму сховищі секретів, а потім використовуйте його для наступних платіжних викликів.

4. Створіть рахунок

Прочитайте GET /api/v1/networks. Використайте увімкнену мережу й готовий токен із його фактичною адресою та кількістю знаків після коми.
Збережіть ключ ідемпотентності разом із рахунком у своїй системі перед надсиланням запиту.
Викличте POST /api/v1/shops/{shop_id}/invoices:

Поле	Значення
`chain_id`	ID обраної мережі з API; ціле число.
`token`	Адреса обраного токена з API.
`amount`	Сума рахунку в найменших одиницях токена; рядок цілого числа.
`external_id`	Опціональне посилання на запис у вашій системі.

Для багаторазової адреси поповнення викличте /deposits без amount. Щоб дати платнику обрати серед кількох токенів або мереж, надішліть assets замість chain_id і token; див. Депозити та рахунки.

Після таймауту повторіть той самий запит із тим самим ключем. Сам лише external_id не запобігає дублікатам.

5. Дочекайтеся адреси, потім оплати

Збережіть id з відповіді 202. Опитуйте:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Дочекайтеся непорожньої address, потім поділіться payment_url. Продовжуйте опитувати цей самий ендпоінт для status і received. Отримуйте сповіщення про зміни через вебхуки.

Прочитайте Статус рахунку та депозиту перед записом оплати рахунку: funded, settled, скасування й багаторазові депозити мають різні значення. Фіксуйте кожне бізнес-оновлення один раз.

Читання документації без браузера

Почніть із llms.txt для покажчика сторінок і OpenAPI для структурованих контрактів. Інструменти читання перелічують експорти в Markdown і повнотекстові.