# Общая информация

> Техническая спецификация интеграции приёма крипто-платежей и выплат через 2328.io.

Добро пожаловать в документацию API 2328.io. Этот справочник описывает, как интегрировать приём крипто-платежей и выплаты в ваше приложение.

## Начало работы

Чтобы начать интеграцию:

1. Создайте мерчант-аккаунт и проект на [2328.io](https://2328.io)
2. Получите **project UUID** и **API key** в настройках проекта
3. Сгенерируйте отдельный **Payout API key**, если планируете использовать выплаты
4. Прочитайте раздел [Authentication](/docs/authentication), чтобы узнать, как подписывать запросы
5. Сделайте свой первый вызов [Create Payment](/docs/payments)

## Базовый URL

Все продакшен-запросы к API используют следующий базовый URL:

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

> **WARNING:** Все запросы должны выполняться по **HTTPS**. Запросы без HTTPS блокируются.

## Что можно делать

С помощью API 2328.io вы можете:

- **Принимать крипто-платежи** — создавать платёжные сессии и перенаправлять клиентов на хостед-чекаут или Telegram MiniApp
- **Выводить средства** — программно отправлять выплаты с баланса мерчанта на любой блокчейн-адрес
- **Проверка балансов** — баланс счетов мерчанта по каждой валюте, эквивалент в USD и суммы, заблокированные AML
- **Использовать статические кошельки** — создавать постоянные адреса для депозитов, привязанные к пользователю или заказу
- **Получать курсы** — узнавать актуальные курсы для пар фиат и крипто в реальном времени
- **Получать webhook'и** — мгновенно узнавать об изменении статуса платежа
## Лимиты запросов

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 — два способа работы с одним и тем же платёжным API. H2H не делает платёж менее защищённым и не отменяет подпись: счёт всё равно создаётся с вашего backend, адресом и статусом управляет 2328.io, а окончательное состояние платежа определяется по подписанным webhook-уведомлениям.

## Обязательные правила интеграции

Эти правила относятся к любой production-интеграции:

- **Только через сервер** — API-ключи не должны попадать в браузер, мобильное приложение, логи, аналитику или скриншоты службы поддержки.
- **Десятичные числа строками** — передавайте и храните денежные значения как строки. Не округляйте криптовалютные суммы и обменные курсы двоичной арифметикой с плавающей точкой.
- **Неизменяемые ключи идемпотентности** — создайте `order_id` до первого запроса и сохраните вместе с ним всё тело запроса. Повтор с тем же `order_id` может вернуть исходный объект, не применив изменённые поля.
- **Подтверждение через webhook** — редирект, клиентский опрос, предоставленный пользователем хеш транзакции или HTTP-тайм-аут сами по себе не доказывают оплату.
- **Сначала проверка и дедупликация, потом изменение данных** — проверьте HMAC, атомарно зарегистрируйте ключ идемпотентности, ровно один раз обновите заказ или баланс и быстро верните HTTP 200.
- **Регулярная сверка** — периодически запрашивайте статусы платежей, статических кошельков и выплат, чтобы потерянный webhook не оставил системы в разных состояниях.
- **Доступность меняется динамически** — проверяйте пары «валюта/сеть» через `/v1/directions`: даже у поддерживаемого актива отдельное направление ввода или вывода может быть временно отключено.
- **Заранее определённая обработка статусов** — до запуска решите, как продукт обрабатывает недоплату, переплату, истечение срока, AML-блокировку, резервный сценарий конвертации и неоднозначный тайм-аут внешнего сервиса.

## Какие данные рекомендуется сохранять

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

Для статического кошелька храните `uuid` кошелька, адрес, валюту, сеть, ссылку на клиента или счёт, статус и URL webhook отдельно от записей о депозитах. У каждого депозита должны быть собственные `uuid` транзакции, `txid`, статус, полученная сумма, сумма мерчанта и результат конвертации.