# Загальна інформація

> Технічна специфікація для інтеграції обробки криптовалютних платежів та виплат із 2328.io.

Ласкаво просимо до документації API 2328.io. Цей довідник описує, як інтегрувати обробку криптовалютних платежів та виплат у вашу програму.

## Початок роботи

Щоб розпочати інтеграцію:

1. Створіть мерчант-акаунт та проєкт на [2328.io](https://2328.io)
2. Отримайте **project UUID** та **API key** у налаштуваннях проєкту
3. Згенеруйте окремий **Payout API key**, якщо плануєте використовувати виплати
4. Прочитайте розділ [Автентифікація](/docs/authentication), щоб дізнатися, як підписувати запити
5. Виконайте свій перший виклик [Створити платіж](/docs/payments)

## Базовий URL

Усі продакшн-запити до API використовують такий базовий URL:

```
https://api.2328.io/api
```

> **WARNING:** Усі запити мають здійснюватися через **HTTPS**. Запити без HTTPS блокуються.

## Що ви можете робити

За допомогою API 2328.io ви можете:

- **Приймати криптоплатежі** — створювати платіжні сесії та перенаправляти клієнтів на хостинговий checkout або Telegram MiniApp
- **Виводити кошти** — програмно надсилати виплати з мерчант-балансу на будь-яку блокчейн-адресу
- **Перевірка балансів** — баланс рахунків мерчанта за кожною валютою, еквівалент у USD та суми, заблоковані AML
- **Використовувати статичні гаманці** — генерувати постійні депозитні адреси, прив'язані до користувача або замовлення
- **Отримувати курси обміну** — отримувати курси у режимі реального часу для пар фіат/крипто
- **Отримувати webhooks** — отримувати миттєві сповіщення про зміну статусу платежу
## Обмеження частоти запитів

API дозволяє до **10 запитів на секунду на проєкт**. Запити, що перевищують ліміт, отримують HTTP-відповідь `429 Too Many Requests` — зачекайте та повторіть запит.

## Виберіть правильний інтеграційний шаблон

| Вимога | Рекомендований шаблон | Чому |
|-------------|---------------------|-----|
| Дозвольте клієнту обрати спосіб оплати | Хостингове оформлення замовлення | Створіть платіж та перенаправте на `result.url`; 2328.io показує наявні напрямки. |
| Тримайте клієнта всередині власного оформлення замовлення | Пряма адреса на **H2H** рахунок-фактуру | Надішліть `to_currency` та `network` під час створення платежу; відобразіть повернуті `address`, `payer_amount`, та `qr`. |
| Списувати точно `25 USDT` або `0.001 BTC` | Рахунок-фактура в криптовалюті | Помістіть криптовалюту в `currency` і точну десяткову суму в `amount`. |
| Надайте кожному користувачу повторно використовувану депозитну адресу | Статичний гаманець | Адреса постійна і може приймати багато незалежних депозитів. |
| Нормалізуйте вхідні активи в одну валюту балансу | Автоматичне конвертування | Налаштуйте правила проєкту на панелі управління та використовуйте результат `convert` після завершення конвертації. |
| Обміняйте існуючий баланс продавця | Ручне конвертування | Попередній перегляд з `/v1/convert/price`, потім виконайте з `/v1/convert`. |
| Надішліть кошти на адресу блокчейну | Виплата | Використовуйте окремий API-ключ для виплат, спочатку розрахуйте суму і погодьте статус виплати. |

> **INFO:** Хостингова каса та H2H — це два представлення одного й того самого Payment API. H2H не створює слабший або непідписаний платіж: на бекенді все одно створюється рахунок, 2328.io досі володіє адресою та статусом, а підписані вебхуки залишаються авторитетними для розрахунків.

## Інваріанти інтеграції

Ці правила застосовуються до кожної інтеграції у виробництві:

- **Backend only** — тримайте API-ключі поза браузерами, мобільними додатками, журналами, аналітикою та скріншотами підтримки.
- **Decimal strings** — відправляйте та зберігайте гроші як рядки. Ніколи не округлюйте криптовалюту або обмінні курси за допомогою бінарної чисельної арифметики з плаваючою комою.
- **Immutable idempotency keys** — генеруйте `order_id` перед першим запитом і зберігайте повний запит разом із ним. Повторна спроба з тим самим `order_id` може повернути оригінальний об'єкт замість застосування змінених полів.
- **Webhook-first settlement** — перенаправлення, опитування клієнтом, хеші транзакцій, надані користувачами, та тайм-аути HTTP не є доказом оплати.
- **Verify, deduplicate, then mutate** — перевіряйте HMAC, атомарно отримуйте запис ідемпотентності, оновлюйте замовлення/баланс один раз і швидко повертайте HTTP 200.
- **Reconciliation** — періодично перевіряйте статус оплати, статичного гаманця та виплат, щоб загублений вебхук не залишав постійної невідповідності.
- **Dynamic availability** — перевіряйте пари валюта/мережа за допомогою `/v1/directions`; підтримуваний актив все ще може мати тимчасово відключений один напрямок депозиту або зняття коштів.
- **Explicit status policy** — вирішіть, як ваш продукт обробляє часткові платежі, переплату, термін дії, блокування AML, резервне перетворення та неоднозначні тайм-аути вищого рівня перед запуском.

## Рекомендовані дані для збереження

Для платежів зберігайте принаймні `uuid`, `order_id`, оригінальне тіло запиту, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, останні `payment_status`, `txid`, `payment_amount`, `merchant_amount`, необов'язковий блок `convert` та необроблений перевірений вебхук.

Для статичних гаманців зберігайте гаманець `uuid`, адресу, валюту, мережу, посилання на клієнта/рахунок, статус та URL для зворотного виклику окремо від записів депозитів. Кожен депозит потребує власної транзакції `uuid`, `txid`, статусу, отриманої суми, суми торговця та результату конверсії.