cursor、取引の読み取りではpage_tokenを使用)。
金額は小数の文字列で表され、通貨はISO 4217のcurrencyフィールドで別に示されます。
日付はISO 8601形式で、国はISO alpha-3の国コードで表されます。
読み取りに対して課金されることは一切ありません。
口座
GET /v3/bank/connections/{id}/accounts/ は接続の口座一覧を取得し、GET /v3/bank/accounts/{account_id}/ は1件の口座を返します。
人が同じ銀行口座を再度接続したときにその口座を識別するには
account_refを、1つの接続内のあらゆる処理にはidを使用してください。
残高
GET /v3/bank/accounts/{account_id}/balances/ は、基準日付きの種別付き残高を返します。
type は booked、available、expected のいずれかです。iso_type には、銀行が提供している場合にその銀行の ISO 20022 コードが入ります。
取引
GET /v3/bank/accounts/{account_id}/transactions/は日付範囲を読み取ります。
date_fromとdate_to(銀行が報告する暦日で、両端を含みます)、status(既定ではbookedとpendingの両方)、limit(最大500)、page_tokenを受け付けます。
並び順はeffective_dateの降順、次にidです。
idは、Diditが発行するもので、初めて確認された時点で保存されます。同じ取引は、読み取り、同期、更新をまたいでも同じidを保ちます。identity_qualityは、この保証の強さを示します。bank_referenceとroute_idは安定しています。derivedは、取引が内容によって照合されたことを意味します。そのため、銀行による訂正はremoved1件とadded1件として表示される場合があります。statusはbookedまたはpendingです。保留中の取引には独自のidがあります。銀行が計上すると、計上済みの取引はaddedとして届き、保留中の取引はreason: pending_booked付きのremovedとして届きます。pending_idは、銀行がこの2件を紐付けている場合にのみ設定されます。amountは符号付きです。負の値は支出を意味します。directionは同じ符号を示します。bank_referenceは銀行の変更不可の記帳参照番号で、銀行が提供しない場合はnullになります。Didit がこの値を生成することはありません。categoryは、該当する場合に Didit が独自に行う分類です。- 計上済みの取引に対する銀行による訂正は
modifiedになります。取消は新しい取引であり、銀行が紐付けている場合はreverses_idが設定されます。
銀行が送信しないフィールドはnullになります
銀行が送信しないフィールドは、すべてnullになります。
金融機関は、送信することが分かっているフィールドをtransaction_fieldsに記載します。また、pending_transactions、pending_linkage、balance_types、history_days_maxも記載するため、本番環境で欠落に後から気づくことがありません。
項目の少ない銀行を想定してコードをテストするには、サンドボックスのsparse_fieldsテスト用顧客を使用してください。
日付範囲のページング
has_moreがtrueの間は、page_tokenを使って読み取りを続けます。
トークンは、読み取りのスナップショットを1時間固定します。最初のページの後に追加された取引はそのスナップショットに含まれません。各行は現在の状態で返されます。ページング中に削除された行は後続のページから除外され、変更フィードに表示されます。
期限切れのトークンは410 page_expiredで応答します。その場合は、元のクエリから読み取りをやり直してください。
変更フィード
GET /v3/bank/connections/{id}/transactions/sync/ は、cursor以降に接続のすべての口座で変更された内容を返します。
- 空の cursor を指定すると、現在のすべての取引が
reset: true付きのaddedとして返されます。取引を追加するのではなく、保存しているコピーをこの内容で置き換えてください。 has_moreがtrueの間は、page_tokenを使って取得を続けてください。has_more: falseのレスポンスを受け取った後にのみnext_cursorを保存してください。途中でページの取得に失敗した場合は、保存済みの cursor から再開してください。- cursor は不透明な値で、接続と環境に紐づきます。変更ログは90日間再生可能です。それより古い cursor には、
410 cursor_expiredとbootstrap: trueが返されます。その場合は空の cursor から最初からやり直し、保存しているコピーを置き換えてください。 removed[].reasonは、pending_booked、pending_expired、bank_removed、access_removedのいずれかです。
ヘッダー
取引データを取得する2つの読み取りAPIは、X-RateLimit-* ヘッダーと X-Bank-Last-Synced-At を返します(アプリケーションあたり1分間に600回の読み取りと300回の書き込みまで。これを超えると、Retry-After ヘッダーを含む429が返されます)。
APIのレート制限と、銀行によるデータ取得の制限は別のものです。詳しくは銀行データをオンデマンドで更新するをご覧ください。