# Быстрый старт

Создайте магазин, создайте инвойс и примите платёж через REST API Invoise.

Source: https://docs.invoise.me/ru/start/quickstart/

**Быстрый онбординг с агентом**
Хотите подключиться быстрее? Скопируйте промпт и передайте своему агенту — он поможет настроить магазин и проверить первый инвойс.

```text wrap
Помоги подключить Invoise к моему проекту. Прочитай https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json и https://docs.invoise.me/ru/agents/integration.md.

Используй существующий доступ или помоги пройти вход, создать мерчанта, магазин и API-ключ. Если входишь кошельком, спроси мой email до создания мерчанта. Уточни у меня адрес получателя до создания магазина. Получай доступные сети, токены, decimals и комиссии из API.

Начни с Sandbox: создай инвойс, получи payment_url, подключи вебхуки с проверкой подписи и защитой от повторов, проверь оплату через GET. Сохраняй Idempotency-Key до запросов. В конце покажи результат проверки и что нужно для приёма реальных платежей.
```



Это обычный способ подключить Invoise к сайту или бэкенду: человек входит в
интерфейс, настраивает магазин, а сервер дальше работает с API по ключу.

Делаете агента, который работает без браузера и без почты? Вам в раздел
[Вход агента](https://docs.invoise.me/ru/agents/sign-in/). Эта страница исходит из того, что настройку
делает человек.

## 1. Войдите и создайте магазин

Откройте [platform.invoise.me](https://platform.invoise.me) и войдите по коду на почту или через
Google. При первом входе создаётся мерчант; магазинов у него ещё нет, поэтому
создайте один.

Магазину нужен **получатель** — кошелёк, на который приходят деньги, — либо
магазин платит в ваш [кошелёк Invoise](https://docs.invoise.me/ru/payments/wallet/). Получателя и
необязательного делегата можно изменить позже; уже созданные инвойсы и адреса
сохраняют значения на момент создания.

Хотите потренироваться без реальных средств — создайте sandbox-магазин. См.
[Sandbox](https://docs.invoise.me/ru/payments/sandbox/).

## 2. Создайте API-ключ

В магазине создайте ключ с правами `read` и `write`. Он начинается с `ivk_`
и показывается один раз, поэтому сохраните его сразу.

Сервер передаёт его в каждом запросе:

```text
Authorization: Bearer ivk_...
```

Ключ работает только для одного магазина и не может тронуть аккаунт или
команду. См. [API-ключи](https://docs.invoise.me/ru/integration/api-keys/).

## 3. Выберите сеть и токен

```bash
curl https://platform.invoise.me/api/v1/networks
```

Возьмите `chain_id`, адрес токена и `decimals` из ответа. Выберите сеть, включённую для мерчанта, и готовый токен. Доступные активы меняются; не зашивайте их список в код. См. [Сети и токены](https://docs.invoise.me/ru/payments/networks/).

## 4. Создайте инвойс

Суммы — целочисленные строки в минимальных единицах токена. При 6 знаках
`10000000` — это 10 токенов.

Перед запросом задайте переменные окружения:

| Переменная | Значение |
| --- | --- |
| `CHAIN_ID` | `chain_id` выбранной сети из API. |
| `TOKEN_ADDRESS` | `tokens[].address` выбранного токена в этой сети. |
| `AMOUNT` | Сумма инвойса в минимальных единицах, рассчитанная по `tokens[].decimals`. |

```bash
curl -X POST https://platform.invoise.me/api/v1/shops/{shop_id}/invoices \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2a8b1f47-6d0c-4a1f-8f0b-4f2c9f3a77d2' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\"}"
```

Замените `{shop_id}` на ID магазина. Создайте и сохраните уникальный `Idempotency-Key` для этого инвойса; ключ в примере — только образец.

В ответе `202 Accepted` сохраните `id` как `issuance_id`. Код `202` означает принятие запроса на создание, а не оплату клиентом.

Нужен многоразовый адрес для пополнений без фиксированной суммы? Вызовите
`/deposits`. См. [Депозиты и инвойсы](https://docs.invoise.me/ru/payments/deposits-and-invoices/).

## 5. Дождитесь адреса

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

Опрашивайте, пока не вернётся адрес, и отправьте плательщика на `payment_url`
из этого ответа. Это [готовая платёжная страница](https://docs.invoise.me/ru/payments/checkout/) —
адрес, QR-код и статус там уже есть.

## 6. Проверьте оплату

**Инвойс оплачен, когда его `status` — `funded` или `settled`.** При `funded` нужная сумма уже подтверждена, при `settled` инвойс закрыт в блокчейне. Статус можно получить через API, а об изменении узнать через вебхук.

### Через вебхук

До первого платежа зарегистрируйте адрес вашего сервера:

```bash
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-webhook-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'
```

Замените URL на свой публичный HTTPS-адрес и сохраните `secret` из ответа.

1. При получении события проверьте `Invoise-Signature` с этим секретом и отсейте повторы по `Invoise-Event-ID`. [Пример проверки подписи](https://docs.invoise.me/ru/integration/webhooks/#3-проверьте-подпись).
2. `transfer.confirmed` сообщает о подтверждённом входящем переводе. Возьмите `data.issuance_id` и запросите статус инвойса через GET ниже: один перевод может покрывать лишь часть суммы.
3. Если `status` — `funded` или `settled` и `cancelled_at` равен `null`, учтите оплату инвойса в вашей системе один раз. Событие `payout.confirmed` отдельно подтверждает полный учёт пейаута получателю.

### Через API

Запросите состояние инвойса с вашего сервера:

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

Важные поля ответа при оплате:

```json
{
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "cancelled_at": null
}
```

Здесь вся сумма инвойса подтверждена. Учтите оплату инвойса в вашей системе; повторный GET или вебхук не должен зачислить его второй раз.

При `open` продолжайте ждать: оплата ещё не пришла полностью. Можно опрашивать раз в 3–5 секунд и увеличивать интервал при долгом ожидании. `registering` и `reconciling` также не означают успех. Если `cancelled_at` заполнен, обработайте оплату отменённого инвойса отдельно.

Все состояния и особенности депозитов — в [статусе инвойса и депозита](https://docs.invoise.me/ru/payments/status/).

## Одно правило, которое стоит запомнить

Создание инвойса или депозита требует `Idempotency-Key`. Сохраните
ключ: если запрос отвалился по таймауту и непонятно, прошёл он или нет,
отправьте тот же запрос с тем же ключом. Вернётся исходный результат, а не
второй инвойс. См.
[Идемпотентность и ошибки](https://docs.invoise.me/ru/integration/idempotency-and-errors/).