> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # ポイントチャージ API 共通仕様 > Waffo Point Topup とサプライヤー間のインターフェース規約、メッセージ構造、SHA256WithRSA 署名と検証、エラーコード、RSA 鍵の生成。 本ページは**モード B** および**モード C** の連携に適用されます。モード A は API を使用しないため対象外です。 ## 共通インターフェース情報 | 項目 | 説明 | | --------- | -------------------------------------------------------------------------------------------------------------------------- | | API プロトコル | RESTful | | API 形式 | メッセージ本文は JSON 形式（`Content-Type: application/json`）で、UTF-8 エンコード | | 送信方式 | HTTP `POST` | | HTTPS 通信 | TLS 1.2 以上 | | 時間 | 特定の時点を表します。ISO 8601 規格に準拠し、精度はミリ秒単位。型 String、例 `2023-04-01T03:00:00.000Z` | | 通貨 | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 通貨コード標準に準拠。型 String、例 `IDR` インドネシア・ルピア、`PHP` フィリピン・ペソ、`MYR` マレーシア・リンギット | | 金額 | 法定通貨の精度は小数点以下 2 桁、単位はドル。型 String、例 `2.27` | | 国コード | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) 規格に準拠。型 String、例 `IDN` インドネシア、`PHL` フィリピン、`HKG` 香港 | API レスポンスは、HTTP ステータスコードによってリクエスト処理の成功または失敗を示します。 | 区分 | ステータスコード | | ----------------- | ----------------------------------------------------------------------- | | **2XX 成功** | `200` OK | | **4XX クライアントエラー** | `400` 不正なリクエスト、`401` 認証不足、`403` アクセス拒否、`404` 見つかりません、`405` メソッドが見つかりません | | **5XX サーバーエラー** | `500` 内部サーバーエラー、`502` ゲートウェイエラー、`503` サービス利用不可、`504` ゲートウェイタイムアウト | **HTTP `200` は業務上の成功を意味しません。** 通信が正常に行われた（リクエストが到達し、受理され、レスポンスが返った）ことだけを示します。実際の業務結果は、さらに次の 2 点で判断してください。 1. レスポンス本文の `code`。`0` のみが受理成功であり、それ以外は[エラーコード](#エラーコード)に従って処理します。 2. `data` 内の業務ステータスフィールド（`status`、`fulfillmentStatus` など）。 例えば履行が失敗した注文も HTTP `200` かつ `code` が `0` で返却され、失敗の内容は `fulfillmentStatus` の `PAY_SUCCESS_SUPPLY_FAILED` および `failureCode` / `failureReason` に現れます。HTTP ステータスコードだけを見ると成功と誤認します。 ## API メッセージ構造 API リクエストおよびレスポンスメッセージは JSON 形式でフォーマットされ、UTF-8 でエンコードされます。メッセージはヘッダーとボディの 2 つの部分で構成されます。 ディストリビューター（Waffo Point Topup）からサプライヤーへの API リクエスト例： ```json theme={null} { "header": { "Content-Type": "application/json", "X-SIGNATURE": "..." }, "body": { ... } } ``` ここでの `X-SIGNATURE` は、Waffo Point Topup が自身の秘密鍵でボディメッセージ全体に署名した値です。 サプライヤーの API レスポンス例： ```json theme={null} { "header": { "Content-Type": "application/json", "X-SIGNATURE": "..." }, "body": { "code": "xxx", "msg": "xxx", "data": { ... } } } ``` ここでの `X-SIGNATURE` は、サプライヤーが自身の秘密鍵でボディメッセージ全体に署名した値です。リクエストが失敗した場合、`data` は空になります。 ## API セキュリティ Waffo Point Topup とサプライヤー間のメッセージの非否認性を確保するために、トランザクションの署名と検証を行います。署名アルゴリズムには **SHA256WithRSA** を使用します。 Waffo とサプライヤーは、まず相互に RSA 公開鍵を交換します。各当事者は自身の RSA 秘密鍵を厳重に保管し、公開鍵のみを相手側と共有します。 Waffo は自身の RSA 秘密鍵を使用してメッセージに署名し、サプライヤーに送信します。サプライヤーは Waffo の公開鍵を使用してメッセージを検証します。検証に成功した場合、サプライヤーは Waffo のリクエストを処理します。検証に失敗した場合、サプライヤーは Waffo に対して `Invalid Signature`（無効な署名）というエラーを返します。 サプライヤーは自身の RSA 秘密鍵を使用してレスポンスメッセージに署名し、Waffo に返信します。Waffo はサプライヤーの公開鍵を使用してメッセージを検証します。検証に成功した場合、Waffo はサプライヤーのレスポンスを処理します。 **検証に失敗した場合、Waffo は調査を行い、サプライヤーに連絡します。その間、問題が解決するまで、Waffo はサプライヤーへの新規トランザクションの送信を停止します。** これは、サプライヤー側でリクエストの処理が完了しているにもかかわらず、署名検証の失敗により Waffo 側でレスポンスの処理が完了していない可能性があるためです。 Waffo Point Topup とサプライヤー間の SHA256WithRSA 署名・検証フロー ## エラーコード エラーコードの接頭辞による分類： | 接頭辞 | 分類 | | ------- | ----------------------------------------------------------------------------------- | | `A`xxxx | サプライヤー関連エラー | | `B`xxxx | ユーザー関連エラー | | `C`xxxx | システム関連エラー | | `D`xxxx | リスク関連の拒否 | | `E`xxxx | 不明なエラー。サプライヤー側またはサードパーティシステム内の不明なステータスにより発生します。最終的な成功／失敗ステータスを受信するまで取引を再試行する必要があります | | エラーコード | 説明 | HTTP ステータス | | ------- | ------------------------------------------------- | ---------- | | `0` | Success | 200 | | `A0001` | Invalid Api secret key | 401 | | `A0002` | Invalid signature | 401 | | `A0003` | Parameter validation failed | 400 | | `A0004` | Permission denied | 401 | | `A0005` | Purchase face value exceeds maximum value allowed | 400 | | `A0006` | Order does not exist | 400 | | `A0007` | Idempotent param mismatch error | 400 | | `A0008` | Too many requests, please try again later | 400 | | `B0001` | Buyer info does not exist | 400 | | `B0002` | Buyer info does not match | 400 | | `C0001` | System error | 500 | | `C0002` | Order info mismatch error | 500 | | `D0001` | Risk rejection | 406 | | `E0001` | Unknown status | 500 | `E0001`（不明なステータス）を受信した場合、取引を失敗と判断しないでください。明確な成功または失敗の最終ステータスを取得するまで照会を続けてください。 ## RSA 鍵の生成 サプライヤーは openssl ツールを使用して RSA 鍵ペアを生成できます。 [openssl.org/source](https://www.openssl.org/source) から openssl をダウンロードしてインストールしてください。 ```bash theme={null} # 秘密鍵の生成 openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out supplier_private_key.pem # 公開鍵の生成 openssl rsa -in supplier_private_key.pem -pubout > supplier_public_key.pem ``` `supplier_public_key.pem` を Waffo に渡し、Waffo 側の公開鍵を受け取ってください。 **秘密鍵は安全に保管し、絶対に第三者に開示しないでください。** ## 次のステップ リアルタイム取得のリクエスト・レスポンス項目と冪等性の要件。 URL 署名リダイレクト、即時履行、即時履行結果照会。