メインコンテンツへスキップ
継続的な銀行フィードを使うと、会計または簿記の製品は、顧客が再度サインインしなくても、顧客の銀行口座の残高と取引明細を毎日取得できます。 Diditでは、継続的なアクセス権を持つリンクを作成し、新しいデータが届いたときにWebhookを受信し、カーソルを使って変更があった分だけを読み取り、同意の期限切れを監視し、顧客が利用を終了したときに、接続を停止または削除できます。 このガイドでは、ゼロの状態から、1人の顧客向けに毎日フィードを取得するまでの手順を説明します。 同じコードをすべての顧客に使用できます。必要になるのは、顧客と銀行ごとに1つの接続だけです。

必要なもの

  • サンドボックス用アプリケーションの、銀行データ権限を持つAPIキー。クイックスタートを参照してください。
  • bank.*イベントを受信するWebhookの送信先。銀行データのWebhookを参照してください。
  • 顧客ごとの接続ID、変更フィードのカーソル、同意の終了日を保存するデータベースのテーブル。

ステップ1: 継続的アクセス付きのリンクを作成する

  • access: ongoingは、同意が終了するまでアクセスを維持します。consent_daysはリクエストです。実際の日付は銀行が決め、接続情報に表示されます。
  • history_fromは、指定した日付以降の履歴を要求します。たとえば年初からの履歴です。代わりにhistory_days(1〜365)を使うこともできますが、両方を同時に指定することはできません。銀行はこれより少ない履歴しか提供しない場合があります。各口座はhistory_coverageで提供範囲を報告します。
  • ownership.compare: noneは口座名義人の照合をスキップするため、参照用の本人情報は不要です。Diditで確認済みの企業と名義人を照合するにはbusinessを使用します。
  • end_user.referenceは、貴社がクライアントに付与するIDです。検索可能で、同じクライアントが同じ口座を再度接続した場合に、Diditがそれを認識できます。
  • クライアントをホスト型検証ページに案内し、リダイレクトURLで貴社のプロダクトに戻します。
リンクのidをクライアントとともに保存してください。

ステップ2: 接続の完了を待つ

クライアント側の手続きが完了すると、connection_id を含む bank.link.completed が届きます。 ブラウザーの結果は決して信頼しないため、次の方法でこれを確認してください:
connection_id を保存し、bank.connection.created を待ちます。これが届くと、口座、残高、直近の取引を読み取れます(sync.initial_status が succeeded または partial になります)。 過去分の取得が終わると、bank.connection.history_complete が届きます。 口座ごとに、history_coverage.oldest_booking_date で、銀行が実際に提供した履歴の最も古い計上日がわかります。

ステップ3: 最初のコピーを読み込む

空のカーソルを指定すると、現在のすべての取引が reset: true 付きの added として返されます。 ページを順に読み取り、カーソルは最後にのみ保存してください:
  • 最初の読み取りは真のスナップショットです。読み取りの開始時点で接続が持っていたすべての取引を、現在の状態のまま、added として1回ずつ返します。ページを読み取っている間に同期が実行されても、この点は変わりません。
  • ページを読み取っている間に行われた変更は、next_cursor からの次の読み取りで返されます。受け取り済みの取引は modified として再度返され、新しい取引は added として返されます。
  • has_more: false を含むレスポンスを受け取った後にのみ、next_cursor を保存してください。
  • ページの読み取りが途中で失敗した場合は、保存しておいたカーソルから読み取りをやり直してください。
  • 残高は GET /v3/bank/accounts/{account_id}/balances/ で読み取ります。

ステップ4: すべてのWebhookで最新状態を維持する

Didit は、有効な継続中の接続をすべて、銀行によって異なりますが1日に1〜4回、自動で同期します(sync.frequency_per_day)。 同期で変更が保存されると、bank.data.updated がconnection_id、account_ids、件数とともに届きます。 保存済みのカーソルを使って変更フィードを呼び出します:
  • added は新しい取引です。保留中の取引も含まれます。
  • modified は変更された取引で、現在の状態で届きます。それぞれidを基準にアップサートしてください。既に保持している取引は更新し、まだ保持していない取引は追加します。
  • removed にはreasonが付いています。手元にないidは無視してください。保留中の取引が計上されると、その取引はpending_bookedの理由付きでremovedに入り、計上された取引はaddedで届きます。
取引のidをキーとして使用してください。読み取り、同期、更新をまたいでも変わりません。 identity_qualityを確認してください。値がderivedの場合、銀行による訂正がremoved1件とadded1件として表示されることがあります。 読み取りは課金されませんが、データが変わるのは同期が実行されたときだけです。そのため、Webhookごとに1回の読み取りで十分です。 より早く取得するには、Sync Nowを使用してください: オンデマンドで銀行データを更新

Step 5: リセットを処理する

再生可能期間より古いカーソルを使用すると、bootstrap: trueを含む 410 cursor_expired が返されます。 変更ログは90日間再生できるため、日次ジョブでこの状況が発生することは稀です。 空のカーソルから読み直し、既存のコピーは取得結果で置き換えてください。追加はしないでください。 空のカーソルからのすべての読み取りにはreset: trueが含まれます。そのため、新規接続と期限切れのカーソルを同じコードパスで処理できます。

ステップ6: 同意の終了を監視する

同意には有効期限があります: consent.expires_at。 Didit は、有効期限の14日前、7日前、1日前に bank.connection.consent_expiring を送信します。 更新したい場合は、renew_connectionを呼び出してください。残りが30日になるまでは、409 renewal_not_needed で応答します。 エンドユーザーが同意の更新を完了するページは、まだ提供されていません。 エンドユーザーが同意を失効させたままにした場合、接続は renewal_required になります。同期済みのデータは引き続き読み取れます。 詳細は銀行同意の更新をご覧ください。

ステップ7: アクセスを停止して削除する

  • 顧客が貴社の製品の利用をやめた場合は、revoke_connectionを呼び出して直ちにデータの読み取りを停止するか、delete_connectionを呼び出して読み取りを停止し、保存済みのデータを削除してください。
  • 顧客が銀行側での共有を停止すると、bank.connection.revoked イベントが ended_by 付きで届きます。その連携のフィードを停止してください。

料金

継続的アクセスは、有効な接続1件あたり月額で課金されます。 この料金には、接続内のすべての口座、残高、取引、銀行が提供する場合は最大365日分の履歴、自動同期、銀行の上限内でのライブ同期、更新、Webhook、およびすべての読み取りが含まれます。 誰も完了しなかったリンクは無料です。renewal_required、paused、revokedの接続も無料です。 詳しくは料金をご覧ください。

チェックリスト

  • 顧客と銀行ごとに1つの連携を、そのカーソルと同意の終了日とともに保存する。
  • Webhookハンドラーを冪等にし、イベントIDをキーにする。
  • reset: trueでは、お使いのコピーを置き換え、追記はしない。
  • removedを、その理由とともに処理する。
  • 同意のリマインダーを、御社から顧客へ送る通知と連携させる。
  • bank.connection.revokedを受け取ったら、フィードを停止する。
  • サンドボックスのプランのテストに合格する。
最終更新日 2026年11月22日