Resolve API β

Resolve API β とは

Resolve API β は、銀行名・支店名を検索するだけのAPIではありません。 入力された銀行名・支店名から候補を推定し、その候補を自動確定してよいかを decision として返す入力判断APIです。

表記ゆれ、略称、読み、部分入力を許容しつつ、誤登録・誤振込につながり得る入力は、候補が存在していても needs_review または ambiguous として返します。

Search API との違い

Search API は、金融機関コード・支店コードを使った情報の取得や、条件に一致する銀行・支店の検索に使います。 Resolve API β は、ユーザー入力から候補を推定し、自動確定可否まで判断したい場合に使います。

実装フロー

1. ユーザー入力を受け取る
   銀行名と支店名を bank_name / branch_name に指定します。
2. 利用文脈を指定する
   通常用途は default、振込・支払用途は payment、初回登録は onboarding、名寄せは matching を指定します。
3. Resolve APIを呼び出す
   POST /resolve/v1/bank-branch を呼び出します。
4. decisionを確認する
   auto_confirm は最有力候補を採用、needs_review / ambiguous は候補確認または再入力に進めます。
5. 必要に応じてcandidatesを提示する
   候補が複数ある場合は、ユーザーまたはオペレーターに選択させます。

エンドポイント

POST https://apis.bankcode-jp.com/resolve/v1/bank-branch

リクエスト

curl -sS -X POST \
  "https://apis.bankcode-jp.com/resolve/v1/bank-branch?apikey=YOUR_API_KEY" \
  -H "content-type: application/json" \
  --data '{
    "bank_name": "みずほ銀行",
    "branch_name": "東京営業部",
    "context": "default"
  }'

入力値の推奨

Resolve API β は略称・表記ゆれ・部分入力を許容しますが、 自動確定率を高めるには、できるだけ正式名称に近い銀行名・支店名を送信してください。

特に振込・支払用途では context: "payment" を指定し、 銀行、信用金庫、支店、営業部 などの種別まで含めた入力を推奨します。

context の使い分け

context は、Resolve API β をどの業務シーンで利用するかを指定するパラメータです。 同じ bank_name / branch_name でも、利用用途によって 自動確定してよいかの判断基準が変わります。

未指定の場合は default として扱われます。 明確な用途がある場合は、利用シーンに合った context を指定してください。

payment context の注意

payment は、振込・支払用途向けの最も厳格な文脈です。 誤確定による業務影響が大きい用途を想定しているため、他の context よりも auto_confirm の判定が慎重になります。

特に、銀行名・支店名が略称、省略、別名一致、接尾辞除去、補完に依存して候補化された場合は、 候補が存在していても needs_review になりやすくなります。

レスポンス

主なレスポンス項目は以下です。型・required・schemaの機械可読仕様はOpenAPIを参照してください。

プラン別レスポンス

Resolve API β は、利用プランにより候補件数と詳細説明項目の返却範囲が異なります。APIの判定ロジックは共通ですが、Free / Standard ではレスポンスを簡潔にし、Proでは確認理由やデバッグ情報を含められます。

candidates の件数は上限値です。該当候補が上限未満の場合は、実際に見つかった候補だけが返ります。

reason_codes / reason_details / reason_summary_ja は、needs_review や ambiguous になった理由を利用側で説明・記録するためのPro向け項目です。Free / Standard では項目自体が返却されません。

debug は調査・検証用です。通常のアプリケーション実装では decision, best_match, candidates を使って処理してください。

decisionの扱い

needs_review はエラーではありません

needs_review はAPIの失敗ではありません。 候補は提示できるものの、誤確定を避けるために利用側で確認すべき状態です。

例えば、略称が複数候補に該当する場合、支店名が省略されている場合、上位候補と次点候補の差が小さい場合、 payment 用途で正式名称として十分でない場合などに返ります。

利用側では、候補一覧の表示、ユーザーへの再確認、オペレーター確認などに回してください。 needs_review を自動確定扱いにしないでください。

候補が見つからない場合

候補が見つからない場合、decision は ambiguous になります。 この場合、best_match と gap は返却されず、candidates は空配列になります。

利用側では、自動確定せず、入力修正、再入力、または人手確認へ回してください。

レスポンス例

auto_confirm（Free / Standard の例）

{
  "decision": "auto_confirm",
  "best_match": {
    "bank_code": "0001",
    "bank_name": "みずほ銀行",
    "branch_code": "001",
    "branch_name": "東京営業部"
  },
  "gap": 999.0,
  "candidates": [
    {
      "bank_code": "0001",
      "bank_name": "みずほ銀行",
      "branch_code": "001",
      "branch_name": "東京営業部"
    }
  ]
}

needs_review（Pro の例）

{
  "decision": "needs_review",
  "best_match": {
    "bank_code": "0001",
    "bank_name": "みずほ銀行",
    "branch_code": "001",
    "branch_name": "東京営業部"
  },
  "gap": 0.0,
  "candidates": [
    { "bank_code": "0001", "bank_name": "みずほ銀行", "branch_code": "001", "branch_name": "東京営業部" },
    { "bank_code": "0001", "bank_name": "みずほ銀行", "branch_code": "078", "branch_name": "東京法人営業部" }
  ],
  "reason_codes": ["gap_too_small", "below_auto_total"],
  "reason_details": [
    { "code": "gap_too_small", "message_ja": "上位候補と次点候補の差が小さく、誤確定リスクがあるため確認が必要です" }
  ],
  "reason_summary_ja": "上位候補と次点候補の差が小さく、誤確定リスクがあるため確認が必要です"
}

ambiguous（候補なしの例）

{
  "decision": "ambiguous",
  "candidates": []
}

reason_codes の概要

Proプランでは、needs_review になった理由を reason_codes と reason_details で返します。 reason_codes は説明・UI表示・ログ分析・監査補助向けの情報です。

• gap_too_small: 上位候補と次点候補の差が小さい
• below_auto_total: 自動確定に必要な水準に達していない
• generic_branch: 汎用的な支店名のため自動確定しない
• bank_alias_ambiguous: 銀行名略称が複数金融機関に該当する可能性がある
• branch_alias_ambiguous: 支店名略称が同一銀行内の複数支店に該当する可能性がある
• payment_branch_trim: payment用途で支店名の接尾辞除去を含む

全コードは reason_codes 公式定義 を参照してください。

debug

debug は Pro プランで x-debug-resolve: true を指定した場合のみ返却されます。Free / Standard では同ヘッダーを指定しても返却されません。デバッグ情報には、正規化結果、候補スコア、データセットバージョンなどが含まれます。

curl -sS -X POST \
  "https://apis.bankcode-jp.com/resolve/v1/bank-branch?apikey=YOUR_API_KEY" \
  -H "content-type: application/json" \
  -H "x-debug-resolve: true" \
  --data '{
    "bank_name": "みずほ銀行",
    "branch_name": "東京営業部",
    "context": "default"
  }'

β期間中の注意事項

• β期間中は仕様・レスポンス項目・reason_details の文言が調整される可能性があります。
• decision と reason_codes の意味は後方互換を重視します。
• needs_review / ambiguous を自動確定扱いにしないでください。
• 振込・支払用途では context: "payment" の利用を推奨します。
• APIキーを外部公開しないでください。
• レスポンスJSONを共有する場合は、必要に応じて業務上の機微情報をマスクしてください。

結果に違和感がある場合

Resolve API β の結果に違和感がある場合は、以下の情報を添えてお問い合わせください。

• リクエストJSON
• レスポンスJSON
• 期待していた結果
• 実際の業務上の扱い
• 用途: 入力補助 / 登録 / 名寄せ / 振込・支払 など
• 発生日時
• 利用しているアカウントのメールアドレスまたは契約名義

APIキーそのものは送らないでください。

エラー

401 Unauthorized

{
  "message": "Unauthorized",
  "request_id": "39a4cc3e552b6422c3226f6ebb7f382b"
}

422 Validation Error

{
  "detail": [
    { "type": "missing", "loc": ["body", "bank_name"], "msg": "Field required", "input": {} },
    { "type": "missing", "loc": ["body", "branch_name"], "msg": "Field required", "input": {} }
  ],
  "request_id": "0ec2d9e1fd04463890ee6a787ad56e99"
}