# Швидкий старт

Створіть магазин, виставте рахунок і отримайте оплату через REST API Invoise.

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

**Почніть швидше з агентом**
Скопіюйте цей промпт у свого агента, щоб налаштувати магазин і перевірити перший рахунок.

```text wrap
Help me integrate Invoise into my project. Read https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json and https://docs.invoise.me/agents/integration.md.

Use my existing access or help me sign in and create a merchant, shop and API key. If you sign in with a wallet, ask me for my email before creating the merchant. Ask me for the recipient address before creating the shop. Read available networks, tokens, decimals and fees from the API.

Start in Sandbox: create an invoice, get payment_url, connect webhooks with signature verification and deduplication, and check payment through GET. Save Idempotency-Key before sending requests. Finish with the test result and what is needed to accept real payments.
```



Це звичайний спосіб інтегрувати Invoise у сайт чи бекенд: увійдіть як людина,
налаштуйте магазин у кабінеті, а потім нехай ваш сервер звертається до API
з ключем.

Створюєте автономного агента без браузера й пошти? Перейдіть до
[Входу для агента](https://docs.invoise.me/uk/agents/sign-in/) — ця сторінка розрахована на те, що
налаштування виконує людина.

## 1. Увійдіть і створіть магазин

Відкрийте [platform.invoise.me](https://platform.invoise.me) і увійдіть за кодом з email або через Google.
Під час першого входу ви створюєте мерчанта; у нового мерчанта ще немає магазинів, тож
створіть один.

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

Створіть магазин у пісочниці, якщо хочете потренуватися без реальних коштів. Див.
[Пісочницю](https://docs.invoise.me/uk/payments/sandbox/).

## 2. Створіть API-ключ

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

Ваш сервер надсилає його з кожним запитом:

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

Ключ працює лише для одного магазину і не має доступу до вашого облікового запису чи команди. Див.
[API-ключі](https://docs.invoise.me/uk/integration/api-keys/).

## 3. Оберіть мережу й токен

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

Візьміть `chain_id`, адресу токена і `decimals` з відповіді. Оберіть мережу, увімкнену для вашого мерчанта, і готовий токен. Доступні активи змінюються; не зашивайте їхній список у код. Див. [Мережі та токени](https://docs.invoise.me/uk/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/uk/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/uk/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/uk/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/uk/payments/status/) — усі стани й поведінку, специфічну для депозитів.

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

Створення рахунку або депозиту вимагає `Idempotency-Key`. Зберігайте ключ:
якщо запит завершився таймаутом і ви не впевнені, чи він спрацював, надішліть
той самий запит з тим самим ключем знову. Ви отримаєте початковий результат замість
другого рахунку. Див. [Ідемпотентність і помилки](https://docs.invoise.me/uk/integration/idempotency-and-errors/).