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

Від входу через гаманець до оплаченого рахунку — повний шлях для автоматизованого агента.

Source: https://docs.invoise.me/uk/agents/integration/

Це шлях налаштування для агента з [сесією гаманця](https://docs.invoise.me/uk/agents/sign-in/). Якщо у вас уже є ID магазину й API-ключ, переходьте одразу до кроку 4.

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

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

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

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

{"name":"My merchant","email":"owner@example.com"}
```

Обліковий запис, що входив лише через гаманець, має надіслати `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. Створіть магазин

```http
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](https://docs.invoise.me/uk/payments/wallet/) облікового запису: надішліть `"payout_target":"wallet"` без `recipient`. Ваша людина налаштовує цей гаманець у кабінеті; доти створення рахунку повертає `400 wallet_not_ready`. Solana і Tron потребують власного отримувача; див. [Solana і Tron](https://docs.invoise.me/uk/payments/solana-and-tron/).

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

Використайте свою сесію, щоб [створити ключ](https://docs.invoise.me/uk/integration/api-keys/) з `read` і `write`. Збережіть повернутий токен `ivk_` у своєму сховищі секретів, а потім використовуйте його для наступних платіжних викликів.

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

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

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

Для багаторазової адреси поповнення викличте `/deposits` без `amount`. Щоб дати платнику обрати серед кількох токенів або мереж, надішліть `assets` замість `chain_id` і `token`; див. [Депозити та рахунки](https://docs.invoise.me/uk/payments/deposits-and-invoices/#запропонуйте-кілька-токенів-або-мереж).

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

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

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

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

Дочекайтеся непорожньої `address`, потім поділіться `payment_url`. Продовжуйте опитувати цей самий ендпоінт для `status` і `received`. Отримуйте сповіщення про зміни через [вебхуки](https://docs.invoise.me/uk/integration/webhooks/).

Прочитайте [Статус рахунку та депозиту](https://docs.invoise.me/uk/payments/status/) перед записом оплати рахунку: `funded`, `settled`, скасування й багаторазові депозити мають різні значення. Фіксуйте кожне бізнес-оновлення один раз.

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

Почніть із [llms.txt](https://docs.invoise.me/llms.txt) для покажчика сторінок і [OpenAPI](https://docs.invoise.me/openapi.json) для структурованих контрактів. [Інструменти читання](https://docs.invoise.me/uk/agents/reading/) перелічують експорти в Markdown і повнотекстові.