verify-et-api

Verify.et API

このポータブルなスキルは、Node.js、Python、PHP、Go、Java、Ruby、.NET、Rust でのバックエンド連携と、信頼できるバックエンドを経由するモバイルアプリに適用できます。

コアワークフロー

1. 連携箇所を特定します。バックエンドの REST アダプター、チェックアウト／決済の検証、Webhook 受信、ポーリング／SSE ステータス UI、ダッシュボード／レポートの利用状況、またはフレームワーク固有のラッパーなどです。
2. 必要なリファレンスだけを読み込みます。
   • references/api-endpoints.md：認証、エンドポイント、ペイロード、レスポンス、権限、ステータスの流れ。
   • references/bank-specs.md：銀行ごとに明示されたペイロードと、ユニバーサルルーターの識別情報。
   • references/error-codes.md：HTTP エラー、検証エラーコード、再試行の判断、クレジット、クォータ、冪等性の競合。
   • patterns/integration-methods.md：同期、キュー、Webhook、ポーリング、SSE の各フローの選び方。
   • patterns/webhooks.md：アカウントの Webhook 設定（ダッシュボードまたは API）、署名シークレット、テスト配信、署名、再試行。
   • patterns/image-processing.md：領収書写真のオプトイン、QR の後に OCR を行う処理、画像クレジット、マルチパートアップロード。
   • debugging/common-mistakes.md：本番環境で避けるべきアンチパターン。
   • debugging/production-checklist.md：リリース前の検証。
3. コードを変更する前に、ユーザーのコードを確認します。API キーと VERIFY_ET_WEBHOOK_SECRET の保存場所、POST /api/verify の呼び出し箇所、アカウントの Webhook が有効かどうか、領収書写真がマルチパートで送信されているか、202 の処理方法、重複送信の可能性、Verify.et の呼び出しがサーバー側で実行されているかを確認します。
4. Verify.et API キーはサーバー側に保持します。ブラウザーおよびモバイルのクライアントは、Verify.et を直接呼び出すのではなく、ユーザーのバックエンドを呼び出す必要があります。
5. fetch を直接呼び出す処理をあちこちに書くのではなく、サーバー側に Verify.et クライアント／アダプターを 1 つ用意する方法を優先します。
6. 決済およびチェックアウトの試行には Idempotency-Key を送信し、返された Verify.et の requestId を保存します。
7. 200 は同期的に返される終端レスポンス、202 はキューに登録された処理として扱います。アカウントの Webhook を 1 つ登録し、その whsec_ シークレットを保存して、利用に頼る前にエンドポイントが active であることを確認します。202 の場合は requestId を保存します。画面に進行状況を表示する必要がある場合に限り、ポーリングまたは SSE を使用します。エンドポイントが有効になったら webhookUrl は指定しないでください。詳しくは patterns/webhooks.md を参照してください。
8. confirmationHistory.confirmedBefore === true は、確認が繰り返されたことを示すシグナルとして扱います。プロダクトの重複決済ポリシーを適用せずに、決済を無条件に確定しないでください。
9. ユーザーの境界に絞ったテストを追加します。リクエストビルダー、Webhook 署名、画像アップロード、ポーリング、冪等性の競合、エラーマッピングのテストなどです。

統合に関する判断

• POST /api/verify?waitMs=... は、ベストエフォートの利便機能としてのみ使用してください。本番のワークフローは、Verify.et が 202 を返す場合でも動作する必要があります。
• ブラウザーやモバイルアプリが閉じられた場合でもバックエンドが結果を把握できるようにするには、アカウントの Webhook を 1 つ登録してください。ユーザーは API Keys → Webhooks から追加するか、API キーを使用して POST /api/webhook-endpoints を呼び出せます。シークレットを保存し、エンドポイントが有効であることを確認したら、verify リクエストでは webhookUrl を指定しないでください。
• クライアントでシンプルな保留中ステータス画面を表示する必要がある場合は、ポーリングを使用してください。
• 認証済み Web UI で、頻繁にポーリングせず低遅延で更新する必要がある場合は、SSE を使用してください。
• 堅牢なチェックアウト UX には、Webhook とポーリング／SSE の両方を使用してください。Webhook はサーバー側の状態を更新し、ポーリング／SSE はユーザーに表示されるフローを更新します。
• プロダクトがプロバイダーをすでに把握している場合は、明示的な bank ペイロードを使用してください。UI で複数の形式の領収書やリンクを受け付ける場合は、汎用的な reference ペイロードを使用してください。オプションの settlementAccount を指定すると、領収書の支払先が想定した受取人であることを確認できます。詳細は references/api-endpoints.md にあります。
• レシートの写真は、Image Processing を有効にした後に限り、オプションのマルチパート image として送信してください。QR と OCR のどちらを使用するかは Verify.et が選択します。patterns/image-processing.md を参照してください。
• 取り消し不能なフルフィルメントは、終端状態の確認、重複確認ポリシーの確認、およびプロダクトで受取人照合を使用する場合の settlementAccountMatch の確認を済ませてから実行してください。

デバッグの基本情報

診断を開始する前に、次の情報を記録してください。

• リクエストメソッド、URL、本文の形式、使用したヘッダー、および API キーがサーバー側で使用されたかどうか。
• HTTP ステータス、レスポンス本文、x-request-id、Retry-After、X-Verify-Cache。
• Verify.et の requestId、processingStatus、status、error.code、error.retryable。
• 銀行／プロバイダー、生の領収書／参照情報、識別に使用する末尾の数字／電話番号／settlementAccount、アカウント Webhook のステータス、Image Processing の有効状態と残高、およびリクエスト単位のレガシー Webhook URL の有無。
• 同じチェックアウト試行で、同じ Idempotency-Key が再利用されたかどうか。

セキュリティルール

• x-api-key や whsec_ の値を、フロントエンドコード、モバイルアプリ、ログ、スクリーンショット、コミットするファイルに含めないでください。
• エンドポイントのシークレットで生の本文を検証する前に、Webhook のペイロードを信頼しないでください。ルールは patterns/webhooks.md にあります。
• VERIFY_ET_WEBHOOK_SECRET は、受信エンドポイントを提供するサーバー環境に保存してください。API はこのシークレットを一度だけ返します。
• X-Webhook-Event-Id を使って、Webhook の処理を冪等にしてください。
• レート制限や一時的な利用不可に対しては、Retry-After に従ってください。
• ログは有用な情報を残しつつ、機密情報を除外してください。requestId、銀行、ステータス、エラーコードを含め、API キー、Cookie、領収書画像のバイトデータ、完全な認証ヘッダーは含めないでください。

ダッシュボードの設定

Webhook の登録は API キーで実行できます。Image Processing の有効化と画像クレジットの追加には API キーを使用できません。その他のアカウント設定も、ダッシュボードでのみ変更できる場合があります。

これらの設定のいずれかが未設定の場合：

1. 不足している設定、その設定を変更するページ、プロジェクトにコピーして戻す値を伝えてください。
2. ユーザーに選択してもらってください。ユーザー自身で設定するか、サインイン中にブラウザーまたはコンピューター操作ツールを使って設定することを明示的に許可できます。
3. その作業の支援をユーザーが選択するまで、ブラウザーを開いたり、サインインしたり、verify.et を操作したり、プラグインを有効にしたりしないでください。Verify.et の統合を依頼する一般的な依頼は、その許可には当たりません。
4. ブラウザーツールが利用できない場合は、ツールをインストールまたは有効にする前にユーザーに確認してください。
5. パスワードを尋ねたり、保存したり、入力したりしないでください。サインインはユーザー自身が行います。
6. 支払いの完了を明示的に依頼され、かつパックと支払い参照情報が提示されていない限り、支払いまたは画像クレジットの追加を実行しないでください。
7. どちらの方法で設定した場合も、API を使って設定を確認してください。Webhook の確認方法は patterns/webhooks.md にあります。Image Processing は、GET /api/image-processing のレスポンスで data.enabled: true かつ data.balance が正の値であることを確認してください。

ソース

インターネットにアクセスできる場合は、最新の公開ドキュメントを使用してください。

• https://verify.et/docs/get-started
• https://verify.et/docs/api
• https://verify.et/docs/sdk

Verify.et リポジトリ内で作業している場合は、古いドキュメントより実装ソースを優先してください。関連するソースパスは references/api-endpoints.md に記載されています。