Developers

注文と冪等性

注文を作成するとレートが固定され、入金アドレスが割り当てられます。ここは統合ミスが資金を動かす唯一の場所です。冪等性はそこでは便利さの問題ではありません。

公開されたコントラクト、まだ公開されていません

これらのエンドポイントは現在公開されていません。事前に統合を構築できるように文書化されています。それらの形状は確定しており、破壊的な変更は新しいバージョンとチェンジログエントリを経由します。

POST/api/v1/ordersPublished contract, not open

注文の作成

レートをロックし、専用の入金アドレスを返します。注文にはロックされた内訳が含まれます：再現可能であり、数か月後でも適用された正確な価格を再構築できます。Idempotency-Keyヘッダーが必要です。

認証: Authorization: Bearer … 認証を参照

パラメータ

パラメータ
フィールド	型	説明
`quoteId`必須	string	受け入れられた見積もりの識別子。
`beneficiary`必須	object	決済手段スキーマによって課されるフィールド。名前は確認済みの本人確認情報と一致する必要があります：第三者への支払いはできません。
`networkId`必須	string	入金が送信されるネットワーク。返されるアドレスと、一部のネットワークでは必須のメモを決定します。

リクエストbash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

レスポンス — 公開された契約json

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

メモはほとんどのネットワークではnullですが、XRP、Stellar、TONでは必須です。そこでの省略は資金を失うことになります：フィールドが非nullである限り必須として扱ってください。

考えられるエラー: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. 完全なカタログ

GET/api/v1/orders/{reference}Published contract, not open

注文の読み取り

現在の状態とタイムスタンプ付きの遷移履歴。履歴は真実のソースです：追加専用で、書き換えられることはなく、「なぜ注文がその状態に移動したのか」という質問に答えます。

認証: Authorization: Bearer … 認証を参照

リクエストbash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

レスポンス — 公開された契約json

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

考えられるエラー: unauthorized, not_found. 完全なカタログ

冪等性

ネットワーク上でタイムアウトした作成リクエストは、注文が作成されたかどうかを教えてくれません。冪等性キーがない場合、2つの悪い選択肢しかありません: 再試行して2つの注文のリスクを冒すか、再試行せずにゼロのリスクを冒すかです。

ヘッダーhttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

意図ごとに1つのキー

キーは「その注文を作成する」という意図を識別し、HTTPリクエストを識別するものではありません。お客様側の一意のID: カートID、呼び出し前に生成されたUUID、決してカウンターではありません。

リプレイは元の応答を返します

同じキーと本文でリプレイすると、最初のリクエストの応答が同じHTTPステータスで返されます。これにより、タイムアウト後を含め、再試行が安全になります。

同じキー、異なる本文: 競合

応答は明示的な競合です。コンテンツが変更された場合、キーも変更する必要があります。そうしないと、2つの注文のどちらをリプレイすべきか誰にもわかりません。

24時間の保持

その後、キーは忘れられ、リプレイすると新しい注文が作成されます。期間内に再試行するか、読み取りエンドポイントで状態を確認してください。

メモ、それを必要とするネットワーク上で

XRP、Stellar、TONでは、入金アドレスだけでは不十分です。追加の識別子が最終受取人を指定します。これはオフランプ統合における最もコストのかかるインシデント原因です。

メモなしの入金は失われた入金です

メモフィールドはほとんどのネットワークではnullで、それを必要とするネットワークでは非nullです。非nullである限り必須として扱い、アドレスと同じ重みで表示してください。共有アドレスにメモなしで到着した入金は手動回復が必要であり、常に成功するとは限りません。

注文状態

以下の状態は、統合で観測できるものです。遷移はタイムスタンプが付けられて追加され、決して書き換えられません。履歴は「なぜ私の注文がその時点でその状態に移行したのか」という質問に答えます。

注文状態
状態	意味
`QUOTE_LOCKED`	レートが固定されています。注文は受取人の詳細または本人確認を待っています。
`AWAITING_DEPOSIT`	入金アドレスが割り当てられ、入金期間が進行中です。資金を送るのはこの時だけです。
`DEPOSIT_DETECTED`	ネットワーク上で着信トランザクションが確認されましたが、まだ確認されていません。ユーザーを安心させ、何も提供しないでください。
`CONFIRMING`	確認が蓄積されています。必要な数は金額ではなくネットワークによって異なります。
`DEPOSIT_CONFIRMED`	入金が保護されています。コンプライアンスと再価格設定ルールはここから評価されます。
`UNDERPAID`	受け取った金額が許容範囲を超えて期待値を下回っています。3つの結果: 追加、受け取った金額で続行、または返金。
`OVERPAID`	受取金額が予想を超えています。当初金額は固定レートのままですが、超過分は別途処理されます。
`PAYOUT_QUEUED`	送金はキューに入っています。キューにより、複数のワーカーが並行して動作しても、送金が一度だけ確実に送信されます。
`PAYOUT_SENT`	送金は送金経路に送信されました。送信済みは受取済みを意味しません。最終的な遅延は受取人の銀行に依存します。
`COMPLETED`	決済が送金経路によって確認されました。最終状態です。
`PAYOUT_FAILED`	送金経路が送金を拒否または返金しました。自動再試行はありません。原因はほぼ常に詳細にあります。
`REFUNDED`	資金はネットワーク手数料を差し引いた上で、元のアドレスに返金されました。最終状態です。