Bango APIの変更監視｜取引先の社名変更や失効をWebhookで受け取る

Bango API の変更監視を使うと、監視対象に登録した取引先の社名変更やインボイスの失効などを、イベントとして受け取れます。 毎日差分データを取り込んで自前で比較する仕組みを作らずに、取引先マスタを最新に保てます。

この記事では、監視の登録からWebhookの受け取り、取りこぼしの補完までを説明します。

検知できる変更

イベントには、変更後の最新の情報（スナップショット）が入っています。受け取った内容でそのまま取引先マスタを更新できます。

監視できる件数はプランごとに決まっていて、Freeは5件、Starterは100件、Growthは1,000件、Proは10,000件です。

手順1：監視対象を登録する

法人番号（13桁）またはT番号（T＋13桁）を指定して登録します。同じ番号を何度登録しても結果は同じです。

curl -X PUT -H "x-api-key: $BANGO_API_KEY" \
  https://api.bango-api.jp/v1/watch-targets/1180301018771

監視をやめるときは DELETE を送ります。

手順2：イベントの受け取り方を決める

受け取り方は2通りで、どちらもFreeから使えます。

同じイベントをどちらでも扱えるので、普段はWebhookで受け、取りこぼしをPullで補う、という組み合わせができます。

手順3：Webhookを受け取る

ダッシュボードかAPI（POST /v1/webhook-endpoints）で受信先のURLを登録します。受信先には次のヘッダー付きでイベントが届きます。

webhook-id: evt_...
webhook-timestamp: 1767225600
webhook-signature: v1,<base64のHMAC-SHA256>

本文を処理する前に、必ず署名を検証してください。 署名は「webhook-id.webhook-timestamp.受け取った本文そのもの」を、登録時に発行される署名用シークレット（whsec_ で始まる値の後ろをBase64デコードしたもの）でHMAC-SHA256したものです。

import crypto from "node:crypto";

export function verify(headers, rawBody, secret) {
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
  const expected = crypto.createHmac("sha256", key).update(signed).digest("base64");
  // シークレットの切り替え中は複数の署名が空白区切りで届く
  return headers["webhook-signature"]
    .split(" ")
    .some((sig) => sig === `v1,${expected}`);
}

古い時刻のリクエストを受け付けないように、webhook-timestamp が現在時刻から5分以上ずれていたら拒否するのがおすすめです。本番では比較を crypto.timingSafeEqual で行ってください。

受け取り側で気をつけること

• 重複して届くことがあります。 配送は「少なくとも1回」なので、webhook-id で処理済みかを確認してください。
• 順番どおりに届くとは限りません。 イベントのスナップショットに入っている日時で、新しいものだけを反映してください。
• 受信に失敗した分はPullで取り戻せます。 保持期間内のイベントは GET /v1/change-events で取得できます。保持期間はFreeが7日、Starter〜Proが90日、Enterpriseが365日です。
• 国税庁の公表より早くは届きません。 国税庁の公表データを日次で同期しているので、反映は公表のタイミングに左右されます。

使いどころの例

• 取引先の社名が変わったら、取引先マスタと請求書の宛名を自動で更新する
• 支払先のインボイスが失効したら、経理担当にSlackで通知する
• 取引先が閉鎖されたら、支払いの予定を止めて確認する

社名変更と法人番号の関係は法人番号は社名変更で変わるかで、取引先マスタの運用全体は取引先マスタの管理方法で解説しています。

まとめ

Bango API の変更監視は、番号を登録しておけば、取引先の変更をイベントで受け取れる機能です。Webhookで受け、署名を検証し、取りこぼしはPullで補う。この3点を押さえれば、取引先マスタを自動で最新に保てます。

まずはFreeプランの5件で、主要な取引先を監視してみてください。