# 概要

> 2328.io と統合して暗号資産の決済処理および出金を行うための技術仕様。

2328.io API ドキュメントへようこそ。本リファレンスでは、暗号資産の決済処理および出金をアプリケーションに統合する方法を説明します。

## はじめに

統合を始めるには：

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 を使用しないリクエストはブロックされます。

## できること

2328.io API を利用することで、以下が可能です：

- **暗号資産による決済の受付** — 決済セッションを作成し、ホスト型のチェックアウトページまたは Telegram MiniApp に顧客をリダイレクトします
- **資金の出金** — マーチャント残高から任意のブロックチェーンアドレスへプログラム的に出金します
- **残高確認** — 通貨ごとのマーチャント残高、USD 換算、AML でロックされた金額を確認できます
- **固定ウォレットの利用** — ユーザーや注文に紐付く永続的な入金アドレスを生成します
- **為替レートの取得** — 法定通貨と暗号資産のリアルタイムレートを取得します
- **Webhook の受信** — 支払いステータスが変化した際に即座に通知を受け取ります
## レート制限

API はプロジェクトごとに **1 秒あたり最大 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`に入れてください。 |
| 各ユーザーに再利用可能な入金アドレスを提供する | 静的ウォレット | このアドレスは永久的で、複数の独立した入金を受け取ることができます。 |
| 入金された資産を1つの残高通貨に正規化する | 自動変換 | ダッシュボードでプロジェクトルールを設定し、変換が完了したら`convert`の結果を使用します。 |
| 既存のマーチャント残高を交換する | 手動変換 | `/v1/convert/price`でプレビューし、`/v1/convert`で実行します。 |
| ブロックチェーンアドレスに資金を送金する | 支払い | 別のPayout APIキーを使用し、まず計算してから、支払いステータスを照合します。 |

> **INFO:** ホスト型チェックアウトとH2Hは、同じPayment APIの二つの提示方法です。H2Hは弱いまたは署名されていない支払いを作成するわけではありません：バックエンドは引き続き請求書を作成し、2328.ioは引き続きアドレスとステータスを所有し、署名付きWebhookは決済において依然として権威を持ちます。

## 統合不変条件

これらのルールはすべての本番統合に適用されます:

- **バックエンド限定** — APIキーをブラウザ、モバイルアプリケーション、ログ、分析、サポートのスクリーンショットに含めないでください。
- **10進文字列** — お金を文字列として送受信および保存します。暗号通貨や為替レートを二進浮動小数点算術で丸めてはいけません。
- **不変の冪等性キー** — 最初のリクエスト前に`order_id`を生成し、リクエスト全体をそれと共に保持します。同じ`order_id`での再試行は、変更されたフィールドを適用するのではなく、元のオブジェクトを返すことができます。
- **Webhook優先の決済** — リダイレクト、クライアントポーリング、ユーザー提供のトランザクションハッシュ、およびHTTPタイムアウトは支払いの証明にはなりません。
- **検証、重複排除、その後に変更** — HMACを検証し、冪等性レコードを原子的に取得し、注文/残高を一度更新して、HTTP 200を迅速に返します。
- **照合** — 支払い、静的ウォレット、支払い状況を定期的に確認し、ウェブフックの損失が恒久的な不一致を残さないようにする。
- **動的な可用性** — `/v1/directions`で通貨/ネットワークペアを検証する。サポートされている資産でも、入金または出金の一方向が一時的に無効になる場合がある。
- **明示的なステータスポリシー** — 製品を本番稼働させる前に、部分支払い、過払い、期限切れ、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`、ステータス、受領額、マーチャント金額、変換結果が必要です。