integrate-1bill

1BILL の統合

1BILL を 1GO/Raast P2M、1IBFT、カードゲートウェイ、または OneBill という無関係な製品と混同せず、信頼性の高い 1LINK 1BILL 統合を構築します。

まず、調査して分類する

計画やコードの作成に着手する前に、必ずリポジトリを調査してください。1LINK または 1BILL の SDK、クライアント、URL、認証情報、請求事業者のプレフィックス、PSID または顧客番号の生成、照会／支払い／取消／ステータスのハンドラー、スキーマ、データベースレコード、メッセージ署名、精算ファイル、照合ジョブ、テスト、認定関連の成果物を検索してください。

• 統合がすでに存在する場合は、正確な 1LINK 製品、API／カタログのバージョン、組織の役割、環境、エンドポイント、認証／署名方式、実装済みのフローを特定してください。既存設計を最小限の変更で修正してください。
• 統合が存在しない場合は、プロジェクトの言語、フレームワーク、データモデル、セキュリティ、ログ、ジョブ、テストの規約に沿って設計してください。
• リクエストフィールド、レスポンスコード、署名、暗号化、URL、認証情報、プレフィックスの規則、PSID の長さ、タイムアウトの動作を決して推測しないでください。加盟店が現在利用している 1LINK サンドボックス／認定ドキュメントから確認してください。

フローを選択する前に、統合における役割を特定してください。

1. 1BILL API を利用する 1LINK 加盟銀行またはノンバンクの開始機関。
2. 決済用の請求データを提供、または接続する請求事業者。
3. 承認済みパートナーを介した政府機関または公的機関の徴収。
4. 実際には 1BILL ではなく、1GO/Raast P2M またはカード決済を求めている加盟店。

製品を確認する

1BILL は統合請求書支払いレールです。固定額の請求書／バウチャー支払い、変動額／トップアップ支払い、クレジットカード請求書の支払い、パッケージ／バンドルのフローに対応しています。通常、顧客は参加銀行、ウォレット、ATM、または窓口決済チャネルで、請求事業者のプレフィックスが付いた顧客、請求書、または PSID の参照番号を入力します。チャネルは請求の詳細を取得し、支払いを送信します。

1BILL を、埋め込み型のカードフォーム、サブスクリプションエンジン、ウォレットのプッシュ API、または Stripe の即時代替として提示しないでください。要件が QR、エイリアス、IBAN、または Request to Pay による加盟店決済であれば、代わりに 1GO/Raast P2M を検討してください。カード決済であれば、承認済みの決済ゲートウェイを検討してください。

ワークフロー

1. 最新の 1LINK 開発者ポータルの製品選択、非公開 API 仕様／OpenAPI ファイル、オンボーディング資料、認証情報、レート制限、テストデータ、認定テストケース、本番環境への切り替え手順を入手します。
2. 正確なカタログ／API バージョンを記録し、コードを変更する前に既存の実装と比較します。
3. 請求カテゴリ、請求事業者のプレフィックス／参照番号の規則、金額の規則、有効期限、重複支払いのポリシー、支払者に表示するフィールド、内部の請求書ライフサイクルを定義します。
4. 照会、支払い、契約に含まれる場合の取消／取消処理、支払いステータス照会、照合、例外処理を、個別の冪等な操作としてモデル化します。
5. 請求参照番号、金額、有効期限、支払い済みステータス、精算の正本はサーバー側で管理します。クライアントのスクリーンショットやクライアントが報告した結果を決して信頼しないでください。
6. アプリケーションレコード、1LINK リクエスト、チャネル取引、ステータス照会、精算、サポート案件を追跡するために必要な相関識別子を保存します。
7. 現行の認定資料の仕様に厳密に従い、認証情報とメッセージの完全性を保護します。無効、再送、未承認、不正形式のリクエストは安全に拒否してください。
8. 成功した支払いだけでなく、重複、遅延、未着、取消、タイムアウト、不明確な取引もテストします。
9. 本番環境に移行する前に、1LINK サンドボックスでのテストと正式な認定を完了します。切り替え時に変更するのは、承認済みの環境設定だけにしてください。

信頼性ルール

• タイムアウトやトランスポート障害は、ステータス照会または照合によって結果が確認されるまでは不明な結果として扱い、支払いを確認せずに再試行しないでください。
• 請求照会は読み取り専用とし、支払いの記録は契約で定められた一意の取引識別子に基づいて冪等にしてください。
• 外部取引 ID と内部の請求／支払い参照に一意制約を設けてください。
• 金融イベントの状態変更にはトランザクション処理を使用し、追記専用の監査証跡を保持してください。
• ユーザーの完了画面、スクリーンショット、SMS、またはフロントエンドからのリクエストだけを根拠に、請求を支払い済みにしないでください。
• 取引記録を 1LINK／決済レポートと照合し、不一致を運用担当者に通知してください。
• チャネル、参照番号、金額、日時、追跡／取引識別子など、サポートに必要な人が読めるデータを保持しつつ、シークレットや機密情報を含むペイロード全体はログに記録しないでください。

参照先の案内

• references/product-and-api-surface.md を読み、適切な 1LINK 製品を選び、公開情報で確認できる 1BILL の操作を把握してください。
• references/implementation-workflow.md を読み、状態モデリング、照会／支払い／ステータス／取消のフロー、PSID／参照情報の UX、認定について確認してください。
• 認証、金融状態、再試行、ログ記録、照合、本番環境への展開を実装する前に、references/security-and-reliability.md を読んでください。
• 日付が記載された公式ソース、公開ドキュメントの制約、最近のコミュニティ報告、再確認が必要な事項については、references/research-notes.md を読んでください。

検証と出力

関連するフォーマット、lint、型チェック、テストを実行してください。1BILL が見つかったか、ゼロから追加したか、選択したロールと製品、確認したバージョンと非公開の仕様、実装した操作、冪等性の方針、照合計画、認定状況、残っている 1LINK またはパートナー側の設定を報告してください。前提は明確に示し、サンドボックスでの成功を本番承認として説明しないでください。