# Сценарий для агента

Путь от входа кошельком до оплаченного инвойса для автоматического агента.

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

Это настройка для агента с [сессией кошелька](https://docs.invoise.me/ru/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; затем создайте отдельный боевой магазин с `sandbox: false`.

Необязательный EVM-делегат `delegate` нужен только для независимого завершения инвойса вашим кошельком. Адрес биржи для этой роли не подходит.

Получателя и делегата можно изменить позже через `PATCH /api/v1/shops/{shop_id}`. Уже созданные инвойсы и адреса сохраняют значения на момент создания.

Боевой магазин может вместо этого платить в [кошелёк Invoise](https://docs.invoise.me/ru/payments/wallet/) аккаунта: передайте `"payout_target":"wallet"` без `recipient`. Кошелёк настраивает ваш человек в интерфейсе; до этого создание инвойса вернёт `400 wallet_not_ready`. Для Solana и Tron нужен отдельный получатель; см. [Solana и Tron](https://docs.invoise.me/ru/payments/solana-and-tron/).

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

С токеном сессии [создайте ключ](https://docs.invoise.me/ru/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/ru/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` через тот же endpoint. Получайте уведомления об изменениях через [вебхуки](https://docs.invoise.me/ru/integration/webhooks/).

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

## Читайте документацию без браузера

[llms.txt](https://docs.invoise.me/llms.txt) содержит индекс страниц, [OpenAPI](https://docs.invoise.me/openapi.json) — формальные контракты. Markdown и полный текст описаны в [чтении документации](https://docs.invoise.me/ru/agents/reading/).