API REFERENCE

Bango API ドキュメント

法人番号APIとインボイスAPIを統合した通常APIと、変更監視・Webhookの各操作の仕様をまとめています。 通常APIの実行確認は Playground を利用してください。

Playgroundで試す

概要

法人番号APIとインボイスAPIを統合し、法人と個人事業主の両ケースをJSONで返します。

データ更新方針

国税庁の「法人番号公表サイト」と「適格請求書発行事業者公表サイト」の公表データを出典とし、日次で差分同期しています。取り込んだデータは統合・正規化・名寄せを行って提供します。反映のタイミングは国税庁の公表状況に依存するため、常に最新であることを保証するものではありません。各レスポンスの meta.source では、データの出典（name）と、取得できる場合は更新日（updated_at）を確認できます。Bango APIは国税庁の公表データを加工して提供するサービスであり、国税庁が本サービスの内容を保証するものではありません。

認証

通常検索・バッチ・watch登録・変更イベントのpullは x-api-key ヘッダーにAPIキーを指定します。キーはダッシュボードから発行・失効できます。Webhook管理・変更監視画面用APIはログイン利用者の Authorization: Bearer <JWT> を使います。APIキーで管理操作はできません。

レート制限

Freeプランでもバッチ名寄せを含む全エンドポイントを利用できます（通常APIは月500コール、バッチ名寄せは月50件まで）。月次の上限とは別に、プランごとに分あたりのリクエスト上限があります。現在の分あたり上限と残数は、レスポンスの X-RateLimit-Limit / X-RateLimit-Remaining ヘッダーで確認できます（上限超過時は429と Retry-After を返します）。これらの技術的制限は、安定運用のため変更することがあります。

エラー

APIのエラーは RFC 9457 の application/problem+json で返します。エラーコードの意味と回復手順は、変更監視・Webhookのコードを含めて エラーリファレンス にまとめています。変更監視・Webhookの各operationが返すstatusとコードは、下の各operationの表で確認できます。

仕様の正

本ドキュメントとOpenAPI仕様に矛盾がある場合はOpenAPIが正です。フィールドの有無・型・enum値の最終的な参照先はOpenAPI仕様（/v1/openapi.json）とします。

機械可読リソース

OpenAPI仕様とAIエージェント向けの概要を公開しています。

クイックスタート

最短で疎通確認するための手順です。まずは統合レスポンス `GET /v1/companies/{corporate_number}` で法人情報とインボイス情報をまとめて確認します。

  • 1. x-api-key を発行してヘッダーに設定します。

  • 2. GET /v1/companies/{corporate_number} を実行します。

  • 3. 返却された法人情報とインボイス情報（invoice.*）を実装側の型に反映します。

  • 変更監視を使う場合は 変更監視・Webhookの初回導入 のプランごとの上限・watch登録・受信サンプルを確認します。

  • 補足: curlの出力を整形する場合は | jq . を使うと日本語のまま表示できます。python3 -m json.tool は既定の設定で日本語を \uXXXX にエスケープ表示しますが、APIの返却値自体はUTF-8の日本語のままです。

クイックスタートをPlaygroundで試す

バッチ名寄せの使い方

大量データは `POST /v1/batch/match` を起点に非同期で処理します。進捗確認とダウンロード導線までを一連で確認できます。

  • 1. companies に企業名を複数行で入力してジョブを作成します。

  • 2. GET /v1/batch/{job_id} を2秒間隔で確認し status が completed になるまで待ちます。

  • 3. 完了後に GET /v1/batch/{job_id}/download で json / csv を取得します。

バッチ名寄せの使い方をPlaygroundで試す

個人事業主への対応

個人事業主ケースでは、Bango APIのプライバシー保護方針により個人を識別しうる情報を公開レスポンスで非開示とするため、表示・保存ロジックの分岐を事前に設計します。

  • GET /v1/invoice/{registration_number} で kind = individual の場合、corporate_number name name_kana name_en address trade_name popular_name は意図的に null で返します。

  • これは取得失敗やデータ欠損を意味しません。元データ側または内部DBで値を取得・保持できる場合でも、Bango APIでは個人情報・プライバシー保護のため公開APIから再配布しない方針です。

  • インボイス登録番号、登録状態、登録日、取消日、失効日、有効性、country、updated_at など、個人を直接識別する情報に当たらない現行フィールドは引き続き返します。

  • アプリ側では null 前提で表示をフォールバックし、インボイス有効性 (invoice.*) を中心に業務判定を行ってください。

個人事業主への対応をPlaygroundで試す

過去日付での有効性確認

`date=YYYY-MM-DD` を渡すことで、過去時点での登録有効性を判定できます。監査・経費精算用途では必須の確認です。

  • GET /v1/invoice/{registration_number}/valid?date=2024-10-01 のように実行します。

  • date は時刻・タイムゾーンを持たない暦日（YYYY-MM-DD）です。

  • date を省略した場合はJST（日本標準時）の今日を判定基準日とし、レスポンスの date に解決後の日付を返します。現在時点の有効性を確認したいときは date なしで実行できます。

  • 取消日・失効日は当日から無効として判定されます。

  • 返却される valid と cancel_date expire_date を使って、対象日での取引妥当性を判断します。

過去日付での有効性確認をPlaygroundで試す

変更監視・Webhookの初回導入

プランごとの上限を確認し、watchを登録して変更イベントを取得します（最短A）。Webhookで受け取る場合は受信先を設定し、テスト送信で署名検証と応答を確認してから通常イベントの受信に備えます（最短B）。

はじめに（監視対象とPull・Webhook）

監視対象（watch）は、法人番号13桁またはT番号（T + 13桁）で登録する法人・個人事業主です。登録時には現在の公表データをbaselineとして返し、以後に検出した公表データの変化を変更イベント（change_event）として記録します。

変更イベントの受け取り方は2つです。Pullは、APIキーで GET /v1/change-events を呼んで保持期間内のイベントを取得します。incrementalでは保存したcheckpointから続きを取得し、欠落を 410 CHANGE_EVENT_HISTORY_GAP で検知できます。Webhookは、登録したHTTPSの受信先へ署名付きでイベントを送ります。Webhookだけで取りこぼしがないことは保証しないため、必要に応じてPullで補完します。

どちらもFreeから利用できます。監視対象の上限・Webhook通知先の数・イベントの保持期間はプランごとに異なります。

プランごとの上限

プランpullwatchWebhook通知先保持
Free対応5件1件7日
Starter対応100件1件90日
Growth対応1,000件2件90日
Pro対応10,000件3件90日
Enterprise対応一律上限なし10件365日

表は横にスクロールできます。

watch / Webhook通知先はactive件数です。プランごとの上限は 料金プラン で確認できます。

Enterpriseのwatchは一律application上限なし（active_watch_limit=null）です。nullは処理性能や個別の容量保証を意味しません。

最短A: APIキーで変更イベントを取得する

  1. プランごとの上限を確認する

    アカウント登録後、料金プランでプランごとの上限を確認します。変更イベントのpullとWebhookはFreeから利用でき、監視対象の上限と通知先の数はプランごとに異なります。契約中のプランは課金管理で確認します。

  2. 先にcheckpointを保存する

    APIキー管理でキーを発行し、watchを登録する前に GET /v1/change-events?mode=incremental&start=now を呼んで、返った next_cursor をcheckpointとして保存します。start=now は呼び出し時点のstream末尾をcheckpointにするため、watch登録の後に呼ぶと、登録からcheckpoint作成までの間に検知された変更イベントが取得できなくなります。

  3. APIキーでwatchを登録する

    下のcURL例の YOUR_API_KEY と YOUR_IDENTIFIER を置き換えて PUT /v1/watch-targets/{identifier} でwatchを登録し、返るbaseline（現在値のfull snapshot）を自社のマスタへ反映します。identifierは法人番号13桁または T + 13桁です。法人番号を持たない個人事業主もT番号で登録できます。baselineは現在値で、過去の変更通知ではありません。

  4. checkpointから変更イベントを取得する

    保存した next_cursor を cursor に渡してincrementalで続きを取得し、各イベントの subject.version をマスタに保存したbaselineのversionと比較して新しいものだけ反映します。処理を終えたら新しい next_cursor を保存します。保持中の履歴を見るだけなら、開始指定なしのhistoryで先頭から列挙します（best-effortで、完全な履歴ではありません）。Data planeの各リクエストは月間APIコールに計上されます。

最短B: Webhookで変更イベントを受け取る

最短Aでcheckpointを保存しwatchを登録したあと、受信先を設定します。

  1. 受信URLと署名鍵を設定する

    owner / adminが変更監視画面の「Webhook」タブで公開HTTPSの受信URLとevent typeを設定します。管理APIはログイン利用者の Authorization: Bearer <JWT> を使い、APIキーとは別です。作成・鍵更新時に一度だけ表示されるsecretを安全に保管し、受信側に設定します。

  2. テスト送信で受信を確認する

    「Webhook」タブで受信先の詳細を開き、テスト送信で署名検証と2xx応答を確認します。画面の「送信結果」が成功であることを確認してください。管理APIを直接呼ぶ場合はHTTP 200だけで判断せず、結果の success を確認します。endpoint.test は疎通専用で、業務更新・inboxには保存しません。通常イベントはwatch登録後に検出された対象の変更を待ちます。テスト成功は通常イベント受信の証明ではありません。

イベントの種類

company.updated

名称・所在地など、法人固有の公表項目が変わりました。法人に埋め込まれたインボイス情報だけの変化ではこの種類になりません。

company.closed

法人の active が true から false になりました（閉鎖）。

company.deleted

法人の公表データがなくなりました。data.current.company は null になり、公表中のインボイス情報は残ります。

company.restored

なくなっていた法人の公表データが、再び公表されました。

invoice.updated

他の種類に当たらないインボイス登録情報の変化です。将来日付の登録が公表された場合もこの種類です。

invoice.deleted

インボイス登録の公表データがなくなりました。data.current.invoice は null になります。

invoice.validity_changed

インボイス登録の有効性（valid）が反転しました。登録日・取消日・失効日の到来による変化もこの種類で、transition に変化前後と理由が入ります。

  • 1回の変化が複数の種類に当たる場合は、優先順位の高い1つの種類で届きます。すべての変化は changes と transition で確認します。

  • data.current には、法人（company）とインボイス（invoice）の変更後の全項目（full snapshot）が入ります。data.changes は変更前後の差分で、受信側のマスタ更新には data.current を使います。

  • 個人事業主は company が null です。公表されていない個人の情報を補完して返すことはありません。

  • endpoint.test はWebhook受信先の疎通テストで、業務上の変化を表すイベントではありません。subject も data.current も持ちません。

  • 以下は架空の法人の住所変更を表した代表例です（実在の企業ではありません）。

{
  "id": "evt_5b2f8c3e-91d4-4a6b-8e27-3c0f6a9d1b48",
  "object": "change_event",
  "schema_version": "2026-09",
  "type": "company.updated",
  "origin": "source_change",
  "subject": {
    "id": "sub_c3a1e7d2-6f4b-4e89-a0d5-7b2e9f1c8a63",
    "kind": "corporation",
    "version": "12",
    "corporate_number": "1234567890123",
    "registration_number": "T1234567890123"
  },
  "resource": {
    "type": "company",
    "id": "1234567890123"
  },
  "detected_at": "2026-10-01T02:00:00Z",
  "snapshot_at": "2026-10-01T02:00:00Z",
  "effective_date": null,
  "data": {
    "previous": null,
    "current": {
      "company": {
        "corporate_number": "1234567890123",
        "name": "サンプル株式会社",
        "name_kana": "サンプル",
        "name_en": null,
        "name_image_id": null,
        "kind": "株式会社",
        "kind_code": "301",
        "address": {
          "prefecture": "東京都",
          "city": "港区",
          "street": "芝公園四丁目2番8号",
          "full": "東京都港区芝公園四丁目2番8号",
          "post_code": "1050011",
          "prefecture_code": "13",
          "city_code": "13103",
          "prefecture_en": null,
          "city_en": null,
          "image_id": null
        },
        "address_outside": null,
        "active": true,
        "closure": null,
        "assignment_date": "2015-10-05",
        "updated_at": "2026-09-30",
        "search_excluded": null,
        "revision": {
          "sequence_number": null,
          "published_date": null,
          "change_date": null,
          "process": null,
          "correct": null,
          "change_cause": null,
          "latest": null
        },
        "invoice": {
          "found": true,
          "registration_number": "T1234567890123",
          "registered": true,
          "registration_date": "2023-10-01",
          "cancel_date": null,
          "expire_date": null,
          "valid": true,
          "country": "domestic"
        }
      },
      "invoice": {
        "kind": "corporation",
        "corporate_number": "1234567890123",
        "name": "サンプル株式会社",
        "name_kana": "サンプル",
        "name_en": null,
        "trade_name": null,
        "popular_name": null,
        "country": "domestic",
        "address": {
          "prefecture": "東京都",
          "city": "港区",
          "street": "芝公園四丁目2番8号",
          "full": "東京都港区芝公園四丁目2番8号",
          "post_code": "1050011",
          "prefecture_code": "13",
          "city_code": "13103",
          "prefecture_en": null,
          "city_en": null,
          "image_id": null
        },
        "address_request": null,
        "address_inside": null,
        "address_outside": null,
        "active": true,
        "closure": null,
        "assignment_date": "2015-10-05",
        "updated_at": "2023-10-01",
        "revision": null,
        "invoice": {
          "found": true,
          "registration_number": "T1234567890123",
          "registered": true,
          "registration_date": "2023-10-01",
          "cancel_date": null,
          "expire_date": null,
          "valid": true,
          "country": "domestic"
        }
      }
    },
    "changes": [
      {
        "path": "/company/address/city",
        "previous": "千代田区",
        "current": "港区"
      },
      {
        "path": "/company/address/city_code",
        "previous": "13101",
        "current": "13103"
      },
      {
        "path": "/company/address/full",
        "previous": "東京都千代田区丸の内一丁目1番1号",
        "current": "東京都港区芝公園四丁目2番8号"
      },
      {
        "path": "/company/address/post_code",
        "previous": "1000005",
        "current": "1050011"
      },
      {
        "path": "/company/address/street",
        "previous": "丸の内一丁目1番1号",
        "current": "芝公園四丁目2番8号"
      },
      {
        "path": "/company/updated_at",
        "previous": "2015-10-05",
        "current": "2026-09-30"
      },
      {
        "path": "/invoice/address/city",
        "previous": "千代田区",
        "current": "港区"
      },
      {
        "path": "/invoice/address/city_code",
        "previous": "13101",
        "current": "13103"
      },
      {
        "path": "/invoice/address/full",
        "previous": "東京都千代田区丸の内一丁目1番1号",
        "current": "東京都港区芝公園四丁目2番8号"
      },
      {
        "path": "/invoice/address/post_code",
        "previous": "1000005",
        "current": "1050011"
      },
      {
        "path": "/invoice/address/street",
        "previous": "丸の内一丁目1番1号",
        "current": "芝公園四丁目2番8号"
      }
    ],
    "transition": null
  },
  "source": {
    "name": "nta",
    "updated_at": "2026-09-30",
    "revision": null
  }
}

watch登録と署名検証のサンプル

受信したraw bodyをJSON parserへ渡す前に、公式Standard Webhooks SDKと webhook-id / webhook-timestamp / webhook-signature で検証します。再serializeしたJSONでは署名が一致しません。以下は既存受信例からの署名検証の抜粋です（JS 1.1.1 / Python 1.1.0）。HTTP入口・DB・worker・TLSは含みません。

curl 'https://api.bango-api.jp/v1/change-events?mode=incremental&start=now' \
  -H 'x-api-key: YOUR_API_KEY'

curl -X PUT 'https://api.bango-api.jp/v1/watch-targets/YOUR_IDENTIFIER' \
  -H 'x-api-key: YOUR_API_KEY'

通常イベントの受信・重複・再送

COMMIT後に2xxを返し、重複を排除する

署名検証とpayload構造確認後、consumerとevent ID（webhook-id = body.id）を一意キーにしてdurable inboxへ保存し、COMMIT後に2xxを返します。同じIDの再受信は重複として2xxで受け付け、業務副作用を重ねません。署名不正・保存失敗で2xxを返さず、body・header・secretはログに出しません。

順序とsubject versionを確認する

配送はat-least-onceで、順序やexactly-onceは保証しません。古いsnapshotで現在値を上書きしないようsubject versionを比較します。個人事業主の company=null と未知のschema/typeを扱い、未知のイベントを既知の更新として適用しません。

再送期限と重複排除の期間を分ける

一時的な受信失敗は再送対象です。最大10 attemptですが回数は保証せず、期限はcycle開始+96時間とevent保持期限の早い方です。retry / replayではevent IDとbodyは同じで、timestamp・署名は変わります。重複排除の保存期間は5分や96時間ではなく、eventが再到達し得る保持期間と監査要件から決めます。

410・redirect・鍵更新を扱う

410はendpoint全体をgoneにして未完了配送を取り消すため、一時障害で返しません。3xxは追跡しないので最終URLを登録します。漏洩時は鍵のimmediate更新と受信側旧鍵の除去、通常のgraceful更新では旧鍵を24時間併置し、新鍵でテストします。

pull補完・停止・解約

historyとcheckpointを使い分ける

変更イベントのhistoryは保持中履歴のbest-effort列挙で、完全履歴や復旧完了を意味しません。Data APIは古い順、画面の「変更イベント」タブは新しい順で、両者のcursorは流用できません。checkpointとして保存するのはincrementalの next_cursor だけです。Webhookの最新event IDやhistory cursorをcheckpointへ昇格しません。ページ内の受付または業務処理と原子的にcheckpointを進めます。

gapは新checkpointから復旧する

410 CHANGE_EVENT_HISTORY_GAP の復旧は、先に GET /v1/change-events?mode=incremental&start=now で新checkpointを保存→active watchを列挙してPUT / GET-oneのfresh baselineをversion比較で反映→保存checkpointからincremental取得、の順です。この間のwatch編集を止めるか再列挙で照合します。再びgapなら最初からやり直します。失効した業務履歴は復元できません。自動gap修復や汎用pullエンジンは本サンプルに含みません。

pause・resume・replayで停止と再送を分ける

一時停止は画面のpause、対象監視の停止は DELETE /v1/watch-targets/{identifier} です。pauseは新しい配送とclaimを止め、pending / retryingを取り消しますが、送信中の1 attemptは完了し得ます。resumeは停止中のeventや取り消した配送を自動送信しません。exhausted / canceledの既存配送はendpoint active・event未失効の場合にreplayでき、配送自体がないeventはpullで補います。

解約・プラン変更後の停止対象を確認する

解約・プラン変更は課金管理のサブスクリプション管理から行います。発効時に移行先の上限を超える場合は、その種別のactive watch / active Webhook通知先が全件停止します。ProからGrowthへの変更でもwatchが移行先の枠内ならwatchは継続します。停止した対象は上限内に収まるプランへ変更しても自動では再開せず、watchはPUT、endpointは再テストとresumeが必要です。退会入口はアカウント設定です。

各operationの認証・parameter・レスポンスは、下の「変更監視 Data plane」「Webhook Control plane」の各リファレンスと OpenAPI仕様、プランごとの上限は 料金プラン を参照します。導入・受信失敗の相談は お問い合わせ から受け付けます。

稼働状況はステータスページで確認できます。

GET

/v1/companies/{corporate_number}

法人番号検索

13桁の法人番号から法人情報とインボイス情報を返します。

関連ガイド

パラメータ

nameintyperequireddescription
corporate_numberpathstringYes13桁の法人番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/companies/1180301018771'

レスポンス例

{
  "object": "company",
  "schema_version": "2026-08",
  "data": {
    "corporate_number": "1180301018771",
    "name": "トヨタ自動車株式会社",
    "name_kana": "トヨタジドウシャ",
    "name_en": null,
    "kind": "株式会社",
    "kind_code": "301",
    "address": {
      "prefecture": "愛知県",
      "city": "豊田市",
      "full": "愛知県豊田市トヨタ町１番地"
    },
    "active": true,
    "closure": null,
    "assignment_date": "2015-10-05",
    "updated_at": "2019-04-23",
    "invoice": {
      "found": true,
      "registration_number": "T1180301018771",
      "registered": true,
      "registration_date": "2023-10-01",
      "cancel_date": null,
      "expire_date": null,
      "valid": true
    }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/companies/1180301018771",
    "docs": "https://bango-api.jp/docs",
    "invoice": "https://api.bango-api.jp/v1/invoice/T1180301018771"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2019-04-23" },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNoオブジェクト種別（例: company / invoice_issuer / batch_job）
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataobjectNoレスポンス本体。以降のフィールドは data 内側の構造
linksobjectNo関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
metaobjectNosource（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
corporate_numberstringNo13桁の法人番号
namestringNo商号または名称
name_kanastringYes商号または名称（カナ表記）
name_enstringYes商号または名称（英語表記）
kindstringNo法人種別（例: 株式会社）
address.fullstringYes本店所在地の完全住所
activebooleanNo現時点で活動中かどうか
assignment_datestringYes法人番号指定日（YYYY-MM-DD）
updated_atstringYes最終更新日（YYYY-MM-DD）
invoice.foundbooleanNoインボイス情報が見つかったかどうか
invoice.registration_numberstringYesインボイス登録番号（T + 13桁）
invoice.registeredbooleanNo適格請求書発行事業者として登録されているか
invoice.registration_datestringYes登録日（YYYY-MM-DD）
invoice.cancel_datestringYes取消日（YYYY-MM-DD）
invoice.expire_datestringYes失効日（YYYY-MM-DD）
invoice.validbooleanYes現時点で有効な登録番号かどうか
このエンドポイントをPlaygroundで試す
GET

/v1/invoice/{registration_number}

T番号検索

T番号から法人情報または個人事業主情報（個人情報はnull）を返します。

関連ガイド

パラメータ

nameintyperequireddescription
registration_numberpathstringYesT + 13桁の登録番号

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/invoice/T1180301018771'

レスポンス例

{
  "object": "invoice_issuer",
  "schema_version": "2026-08",
  "data": {
    "corporate_number": null,
    "kind": "individual",
    "name": null,
    "address": null,
    "invoice": {
      "found": true,
      "registration_number": "T6810924593403",
      "registration_date": "2026-01-01",
      "valid": true
    }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/invoice/T6810924593403",
    "docs": "https://bango-api.jp/docs",
    "company": null
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2026-01-13" },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNoオブジェクト種別（例: company / invoice_issuer / batch_job）
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataobjectNoレスポンス本体。以降のフィールドは data 内側の構造
linksobjectNo関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
metaobjectNosource（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
corporate_numberstringYes法人の場合は13桁の法人番号、個人事業主はnull
kindstringNo種別（法人または individual）
namestringYes名称。個人事業主ケースではnull
name_kanastringYes名称カナ。個人事業主ケースではnull
trade_namestringYes個人事業主の屋号。存在しない場合はnull
popular_namestringYes個人事業主の通称・旧姓。存在しない場合はnull
addressobjectYes所在地情報。個人事業主ケースではnull
invoice.foundbooleanNoインボイス情報が見つかったかどうか
invoice.registration_numberstringNoインボイス登録番号（T + 13桁）
invoice.registration_datestringYes登録日（YYYY-MM-DD）
invoice.cancel_datestringYes取消日（YYYY-MM-DD）
invoice.expire_datestringYes失効日（YYYY-MM-DD）
invoice.validbooleanNo現時点で有効な登録番号かどうか
注意事項
  • 個人事業主ケースでは name / address / trade_name / popular_name は null です。
このエンドポイントをPlaygroundで試す
GET

/v1/invoice/{registration_number}/valid

過去日付有効性確認

指定日付時点で登録番号が有効かを判定します。

関連ガイド

パラメータ

nameintyperequireddescription
registration_numberpathstringYesT + 13桁
datequerystringNo判定対象の暦日（YYYY-MM-DD、時刻・タイムゾーンなし）。省略時はJST今日で判定します。

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'date=2024-10-01' \
  'https://api.bango-api.jp/v1/invoice/T1180301018771/valid'

レスポンス例

{
  "object": "invoice_validity",
  "schema_version": "2026-08",
  "data": {
    "registration_number": "T1180301018771",
    "date": "2024-10-01",
    "valid": true,
    "registration_date": "2023-10-01",
    "expire_date": null,
    "cancel_date": null
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/invoice/T1180301018771/valid",
    "docs": "https://bango-api.jp/docs",
    "invoice": "https://api.bango-api.jp/v1/invoice/T1180301018771"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": "2021-10-28" },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNoオブジェクト種別（例: company / invoice_issuer / batch_job）
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataobjectNoレスポンス本体。以降のフィールドは data 内側の構造
linksobjectNo関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
metaobjectNosource（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
registration_numberstringNo判定対象の登録番号（T + 13桁）
datestringNo判定対象日（YYYY-MM-DD）
validbooleanNo対象日での有効性
registration_datestringYes登録日（YYYY-MM-DD）
expire_datestringYes失効日（YYYY-MM-DD）
cancel_datestringYes取消日（YYYY-MM-DD）
注意事項
  • date は時刻を持たない暦日として扱います。取消日・失効日は当日から無効です。
  • date を省略した場合はJST（日本標準時）の今日を判定基準日とし、レスポンスの date にその解決後の日付を返します。
このエンドポイントをPlaygroundで試す
GET

/v1/companies/search

法人名検索

部分一致（partial）または法人格除去完全一致（exact）で検索します。

関連ガイド

パラメータ

nameintyperequireddescription
qquerystringYes検索クエリ（1文字以上200文字以内）
modequerystringNopartial / exact
prefecture_codequerystringNo都道府県コード（2桁）
limitquerynumberNo件数（1〜50）

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'q=トヨタ自動車' \
  --data-urlencode 'mode=partial' \
  --data-urlencode 'limit=2' \
  'https://api.bango-api.jp/v1/companies/search'

レスポンス例

{
  "object": "list",
  "item": "company_summary",
  "schema_version": "2026-08",
  "data": [
    {
      "object": "company_summary",
      "corporate_number": "1180301018771",
      "name": "トヨタ自動車株式会社",
      "name_kana": "トヨタジドウシャ",
      "prefecture_code": "23",
      "city_code": "23211",
      "score": 0.857143
    },
    {
      "object": "company_summary",
      "corporate_number": "1430005009042",
      "name": "トヨタ自動車北海道労働組合",
      "name_kana": "トヨタジドウシャホッカイドウ",
      "prefecture_code": "01",
      "city_code": "01213",
      "score": 0.857143
    }
  ],
  "has_more": true,
  "offset": 0,
  "limit": 2,
  "facets": null,
  "links": {
    "self": "https://api.bango-api.jp/v1/companies/search?q=...",
    "docs": "https://bango-api.jp/docs",
    "next": "https://api.bango-api.jp/v1/companies/search?q=...&limit=2&offset=2"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": null
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNo一覧エンベロープ種別（list 固定）
itemstringNodata 配列要素のオブジェクト種別（例: company_summary / batch_result_row）。各要素の object も同値
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataarrayNo一致した要素の配列。以降のフィールドは各要素（item）の構造
has_morebooleanNo続きの実在を示す。offset+limit が上限に達した場合 links.next はnull（打ち切り）
offsetnumberNo取得開始位置（0起点）
limitnumberNo取得件数上限
linksobjectNoself/docs は常設、next は最終ページ/打ち切り時はnull
metaobjectNosource（一覧では updated_at=null）・rate_limit・quota。batch_rows は batch系のみnon-null
facetsobjectYesfacetsパラメータ指定時のみnon-null（軸名→{value,count}[]）。それ以外はnull
corporate_numberstringNo候補企業の法人番号
namestringNo候補企業の名称
name_kanastringYes候補企業の名称カナ
prefecture_codestringYes都道府県コード（2桁）
city_codestringYes市区町村コード
scorenumberNo検索順位付けに使う相対スコア（0〜1）。正解確率・信頼度ではなく、mode=partial では接頭辞一致などで複数候補が同値になりうる。
注意事項
  • mode=partial で q が1文字の場合は 400 VALIDATION_ERROR です。
  • mode=exact は1文字でも検索できます。
このエンドポイントをPlaygroundで試す
POST

/v1/batch/match

バッチ名寄せ受付

企業名リストを投稿して非同期ジョブを作成します。

関連ガイド

パラメータ

nameintyperequireddescription
companiesbodystring[]Yes企業名配列（最大1,000件）

リクエスト例

curl -X POST -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"companies":["株式会社サンプル","合同会社サンプル"]}' \
  'https://api.bango-api.jp/v1/batch/match'

レスポンス例

{
  "object": "batch_job",
  "schema_version": "2026-08",
  "data": {
    "job_id": "batch_abc123",
    "status": "queued"
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/match",
    "docs": "https://bango-api.jp/docs",
    "status": "https://api.bango-api.jp/v1/batch/batch_abc123"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNoオブジェクト種別（例: company / invoice_issuer / batch_job）
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataobjectNoレスポンス本体。以降のフィールドは data 内側の構造
linksobjectNo関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
metaobjectNosource（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
job_idstringNo作成されたバッチジョブID
statusstringNo初期状態（queued）
このエンドポイントをPlaygroundで試す
GET

/v1/batch/{job_id}

バッチ進捗取得

job_id の進捗と結果を取得します。

関連ガイド

パラメータ

nameintyperequireddescription
job_idpathstringYesバッチジョブID

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/batch/job_00000000-0000-4000-8000-000000000000'

レスポンス例

{
  "object": "batch_job",
  "schema_version": "2026-08",
  "data": {
    "job_id": "batch_abc123",
    "status": "processing",
    "progress": { "done": 450, "total": 1000 }
  },
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/batch_abc123",
    "docs": "https://bango-api.jp/docs",
    "download": null
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNoオブジェクト種別（例: company / invoice_issuer / batch_job）
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataobjectNoレスポンス本体。以降のフィールドは data 内側の構造
linksobjectNo関連リンク。self/docs は常設、関連キー（invoice/company/next 等）はエンドポイント別で値なしはnull
metaobjectNosource（NTA更新日）・rate_limit・quota（api_requests/batch_rows）。batch_rows は batch系のみnon-null
job_idstringNo対象バッチジョブID
statusstringNoジョブ状態（queued / processing / completed / failed）
progress.donenumberYes処理済み件数
progress.totalnumberYes総件数
summary.confidentnumberYesconfident 判定件数（completed時）
summary.reviewnumberYesreview 判定件数（completed時）
summary.unmatchednumberYesunmatched 判定件数（completed時）
このエンドポイントをPlaygroundで試す
GET

/v1/batch/{job_id}/download

バッチ結果ダウンロード

完了済みジョブの結果を json または csv で取得します。

関連ガイド

パラメータ

nameintyperequireddescription
job_idpathstringYesバッチジョブID
formatquerystringNojson / csv

リクエスト例

curl -G -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'format=csv' \
  'https://api.bango-api.jp/v1/batch/job_00000000-0000-4000-8000-000000000000/download'

レスポンス例

{
  "object": "list",
  "item": "batch_result_row",
  "schema_version": "2026-08",
  "data": [
    {
      "object": "batch_result_row",
      "row_index": 1,
      "input_name": "株式会社サンプル",
      "prefecture_code": "13",
      "confidence": "confident",
      "score": 0.97,
      "candidate_count": 1,
      "matched_corporate_number": "1234567890123",
      "candidates": [
        {
          "corporate_number": "1234567890123",
          "name": "株式会社サンプル",
          "name_kana": "カブシキガイシャサンプル",
          "score": 0.97
        }
      ]
    }
  ],
  "has_more": false,
  "offset": 0,
  "limit": 10,
  "links": {
    "self": "https://api.bango-api.jp/v1/batch/batch_abc123/download",
    "docs": "https://bango-api.jp/docs"
  },
  "meta": {
    "source": { "name": "nta", "updated_at": null },
    "rate_limit": {
      "unlimited": false,
      "limit": 6000,
      "remaining": 598,
      "reset": "2026-01-15T00:01:00Z"
    },
    "quota": {
      "api_requests": { "unlimited": false, "limit": 10000, "remaining": 9876 },
      "batch_rows": { "unlimited": false, "limit": 10000, "remaining": 9000 }
    }
  }
}

レスポンス項目

fieldtypenullabledescription
objectstringNo一覧エンベロープ種別（list 固定）
itemstringNodata 配列要素のオブジェクト種別（例: company_summary / batch_result_row）。各要素の object も同値
schema_versionstringNo現行構造の最終変更年月（YYYY-MM・情報提供専用）
dataarrayNo一致した要素の配列。以降のフィールドは各要素（item）の構造
has_morebooleanNo続きの実在を示す。offset+limit が上限に達した場合 links.next はnull（打ち切り）
offsetnumberNo取得開始位置（0起点）
limitnumberNo取得件数上限
linksobjectNoself/docs は常設、next は最終ページ/打ち切り時はnull
metaobjectNosource（一覧では updated_at=null）・rate_limit・quota。batch_rows は batch系のみnon-null
row_indexnumberNo入力行番号（0起点または1起点）
input_namestringNo入力した企業名
prefecture_codestringYes入力から抽出した都道府県コード（任意）
confidencestringNo判定区分（confident / review / unmatched）
scorenumberNo最良候補の一致スコア（0〜1）
candidate_countnumberNo候補件数
matched_corporate_numberstringYes確定した法人番号（未確定時はnull）
candidates[].corporate_numberstringNo候補の法人番号
candidates[].namestringNo候補の名称
candidates[].name_kanastringYes候補の名称カナ
candidates[].scorenumberNo候補の一致スコア（0〜1）
注意事項
  • 上記は format=json（既定）かつ completed 時のレスポンスで、data 配列に各行（batch_result_row）を並べた一覧エンベロープです。format=csv では同じ結果をCSV文字列で返します。
  • status=queued/processing では 409 BATCH_NOT_COMPLETED を返します。
  • status=failed では 409 BATCH_FAILED を返します。
このエンドポイントをPlaygroundで試す

変更監視 Data plane

APIキーで呼ぶ、監視対象（watch）の登録・停止と変更イベントの取得です。自社のシステムから直接組み込みます。

PUT/v1/watch-targets/{identifier}

監視開始（冪等）

x-api-key

監視を開始し、現在snapshotをbaselineとして返す（request bodyなし）。既にactiveならstarted_atを維持した同じperiodを返し、停止後の再開は新periodを作る。予約済みdowngradeの発効後に枠を超える場合はcapacity_warningを返す（拒否はしない）。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: 最短A: APIキーで変更イベントを取得する / pull補完・停止・解約

パラメータ

nameintyperequireddescription
identifierpathstringYes法人番号（13桁）または登録番号（T+13桁）。構文外は400

リクエスト例

curl -X PUT -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/watch-targets/YOUR_IDENTIFIER'

レスポンス例（200）

監視中の現在状態

個人事業者（T番号のみ）の監視開始

{
  "capacity_warning": null,
  "current": {
    "as_of": "2026-09-15T00:00:00Z",
    "company": null,
    "invoice": {
      "active": null,
      "address": null,
      "address_inside": null,
      "address_outside": null,
      "address_request": null,
      "assignment_date": null,
      "closure": null,
      "corporate_number": null,
      "country": "domestic",
      "invoice": {
        "cancel_date": null,
        "country": "domestic",
        "expire_date": null,
        "found": true,
        "registered": true,
        "registration_date": "2026-01-01",
        "registration_number": "T6810924593403",
        "valid": true
      },
      "kind": "individual",
      "name": null,
      "name_en": null,
      "name_kana": null,
      "popular_name": null,
      "revision": null,
      "trade_name": null,
      "updated_at": null
    }
  },
  "id": "wt_71a2b094-762e-4c90-8da7-2defbff4bcb6",
  "object": "watch_target",
  "started_at": "2026-09-15T00:00:00Z",
  "status": "active",
  "stop_reason": null,
  "stopped_at": null,
  "subject": {
    "id": "sub_ef7af6a2-e24a-4cf7-9857-33057aab4a8e",
    "kind": "individual",
    "version": "6"
  }
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORidentifier書式不正（VALIDATION_ERROR）
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND公開データにsubjectが存在しない（NOT_FOUND）
409RESOURCE_LIMIT_EXCEEDEDactive監視数の上限超過（RESOURCE_LIMIT_EXCEEDED。resource_limit.resource=watch_targets、limit/currentに上限と現在数）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/watch-targets/{identifier}

監視対象の現在状態取得

x-api-key

最新のwatch periodと現在snapshot（company/invoice全体）を返す。停止後も最新periodを返す。応答はエンベロープではなくwatch_target本体（links/metaなし）。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
identifierpathstringYes法人番号（13桁）または登録番号（T+13桁）。構文外は400

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/watch-targets/YOUR_IDENTIFIER'

レスポンス例（200）

監視対象の現在状態

監視中の法人（現在snapshot全体）

{
  "capacity_warning": null,
  "current": {
    "as_of": "2026-10-01T03:00:00Z",
    "company": {
      "active": true,
      "address": {
        "city": "豊田市",
        "city_code": "23211",
        "city_en": null,
        "full": "愛知県豊田市トヨタ町１番地",
        "image_id": null,
        "post_code": "4710826",
        "prefecture": "愛知県",
        "prefecture_code": "23",
        "prefecture_en": null,
        "street": "トヨタ町１番地"
      },
      "address_outside": null,
      "assignment_date": "2015-10-05",
      "closure": null,
      "corporate_number": "1180301018771",
      "invoice": {
        "cancel_date": null,
        "country": "domestic",
        "expire_date": null,
        "found": true,
        "registered": true,
        "registration_date": "2023-10-01",
        "registration_number": "T1180301018771",
        "valid": true
      },
      "kind": "株式会社",
      "kind_code": "301",
      "name": "トヨタ自動車株式会社",
      "name_en": null,
      "name_image_id": null,
      "name_kana": "トヨタジドウシャ",
      "revision": {
        "change_cause": null,
        "change_date": null,
        "correct": null,
        "latest": null,
        "process": null,
        "published_date": null,
        "sequence_number": null
      },
      "search_excluded": null,
      "updated_at": "2026-09-30"
    },
    "invoice": {
      "active": true,
      "address": {
        "city": "豊田市",
        "city_code": "23211",
        "city_en": null,
        "full": "愛知県豊田市トヨタ町１番地",
        "image_id": null,
        "post_code": "4710826",
        "prefecture": "愛知県",
        "prefecture_code": "23",
        "prefecture_en": null,
        "street": "トヨタ町１番地"
      },
      "address_inside": null,
      "address_outside": null,
      "address_request": null,
      "assignment_date": "2015-10-05",
      "closure": null,
      "corporate_number": "1180301018771",
      "country": "domestic",
      "invoice": {
        "cancel_date": null,
        "country": "domestic",
        "expire_date": null,
        "found": true,
        "registered": true,
        "registration_date": "2023-10-01",
        "registration_number": "T1180301018771",
        "valid": true
      },
      "kind": "corporation",
      "name": "トヨタ自動車株式会社",
      "name_en": null,
      "name_kana": "トヨタジドウシャ",
      "popular_name": null,
      "revision": null,
      "trade_name": null,
      "updated_at": "2021-10-28"
    }
  },
  "id": "wt_1533d05a-c51c-4b31-b1da-b47286894586",
  "object": "watch_target",
  "started_at": "2026-09-01T00:00:00Z",
  "status": "active",
  "stop_reason": null,
  "stopped_at": null,
  "subject": {
    "id": "sub_ee7b4514-902a-4c38-867f-3fd740e23489",
    "kind": "corporation",
    "version": "43"
  }
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORidentifier書式不正（VALIDATION_ERROR）
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND一度も監視していない（NOT_FOUND）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

DELETE/v1/watch-targets/{identifier}

監視停止（冪等）

x-api-key

監視を停止し、最新のstopped periodを200で返す（204ではない）。停止済みへの再実行はperiodを増やさず同じ結果を返す。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
identifierpathstringYes法人番号（13桁）または登録番号（T+13桁）。構文外は400

リクエスト例

curl -X DELETE -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/watch-targets/YOUR_IDENTIFIER'

レスポンス例（200）

停止後の最新period

停止後の最新period（法人ブロック削除済み・invoiceは存続）

{
  "capacity_warning": null,
  "current": {
    "as_of": "2026-10-05T00:00:00Z",
    "company": null,
    "invoice": {
      "active": true,
      "address": {
        "city": "豊田市",
        "city_code": "23211",
        "city_en": null,
        "full": "愛知県豊田市トヨタ町１番地",
        "image_id": null,
        "post_code": "4710826",
        "prefecture": "愛知県",
        "prefecture_code": "23",
        "prefecture_en": null,
        "street": "トヨタ町１番地"
      },
      "address_inside": null,
      "address_outside": null,
      "address_request": null,
      "assignment_date": "2015-10-05",
      "closure": null,
      "corporate_number": "1180301018771",
      "country": "domestic",
      "invoice": {
        "cancel_date": null,
        "country": "domestic",
        "expire_date": null,
        "found": true,
        "registered": true,
        "registration_date": "2023-10-01",
        "registration_number": "T1180301018771",
        "valid": true
      },
      "kind": "corporation",
      "name": "トヨタ自動車株式会社",
      "name_en": null,
      "name_kana": "トヨタジドウシャ",
      "popular_name": null,
      "revision": null,
      "trade_name": null,
      "updated_at": "2021-10-28"
    }
  },
  "id": "wt_1533d05a-c51c-4b31-b1da-b47286894586",
  "object": "watch_target",
  "started_at": "2026-09-01T00:00:00Z",
  "status": "stopped",
  "stop_reason": "user_requested",
  "stopped_at": "2026-10-05T00:00:00Z",
  "subject": {
    "id": "sub_ee7b4514-902a-4c38-867f-3fd740e23489",
    "kind": "corporation",
    "version": "44"
  }
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORidentifier書式不正（VALIDATION_ERROR）
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND一度も監視していない（NOT_FOUND）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/watch-targets

監視対象一覧

x-api-key

監視対象のsummary一覧を(started_at, id)昇順のkeyset cursorで返す（offsetなし）。続きはnext_cursorをcursorへ渡す。links.nextは続きがある場合のみ非null。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
statusquerystring (active | stopped | all)No監視状態で絞り込む。cursor併用時は発行時と同じstatusが必須（不一致は400）
limitqueryintegerNo1ページの件数（1〜100）。先頭ゼロ・符号・小数・指数表記は400
cursorquerystringNo前ページのnext_cursor（opaque・署名付き）。組織とstatusに束縛され、改竄・他組織/別statusへの流用は400

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/watch-targets'

レスポンス例（200）

監視対象summary一覧

最終ページ（該当なし・has_more=false）

{
  "data": [],
  "has_more": false,
  "item": "watch_target",
  "limit": 2,
  "links": {
    "docs": "https://bango-api.jp/docs#watch_targets_list",
    "next": null,
    "self": "https://api.bango-api.jp/v1/watch-targets?limit=2&cursor=wl1.d2F0Y2hlcw.c2ln"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "next_cursor": "wl1.ZW5k.c2ln",
  "object": "list",
  "schema_version": "2026-08"
}

続きがあるページ（next_cursorで継続）

{
  "data": [
    {
      "id": "wt_1533d05a-c51c-4b31-b1da-b47286894586",
      "identifier": "1180301018771",
      "started_at": "2026-09-01T00:00:00Z",
      "status": "active",
      "stop_reason": null,
      "stopped_at": null,
      "subject": {
        "id": "sub_ee7b4514-902a-4c38-867f-3fd740e23489",
        "kind": "corporation"
      }
    },
    {
      "id": "wt_71a2b094-762e-4c90-8da7-2defbff4bcb6",
      "identifier": "T6810924593403",
      "started_at": "2026-09-15T00:00:00Z",
      "status": "active",
      "stop_reason": null,
      "stopped_at": null,
      "subject": {
        "id": "sub_ef7af6a2-e24a-4cf7-9857-33057aab4a8e",
        "kind": "individual"
      }
    }
  ],
  "has_more": true,
  "item": "watch_target",
  "limit": 2,
  "links": {
    "docs": "https://bango-api.jp/docs#watch_targets_list",
    "next": "https://api.bango-api.jp/v1/watch-targets?limit=2&cursor=wl1.d2F0Y2hlcw.c2ln",
    "self": "https://api.bango-api.jp/v1/watch-targets?limit=2"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "next_cursor": "wl1.d2F0Y2hlcw.c2ln",
  "object": "list",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORquery不正（VALIDATION_ERROR。status/limit書式・cursor改竄・他組織cursor・status不一致）
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/change-events

変更イベント一覧（history / incremental）

x-api-key

history=保持中履歴のbest-effort列挙（continuity_guaranteed=false・next_after=null。欠落なしは保証しない）。historyは初回リクエスト時点のstream末尾（head）を固定し、続きのページも同じheadまでを返す。列挙開始後に公開されたeventは含まれないため、取得するには新しく一覧を開始する。historyの最終ページはhas_more=falseでもnext_cursorは非null（再利用しても固定headより先は返さず、incrementalのcheckpointにはならない）。

incremental=指定checkpointからの欠落検知付き差分回収（continuity_guaranteed=true。欠落検知は410 CHANGE_EVENT_HISTORY_GAP）。最終ページ・空ページでもnext_cursorは走査済み位置へ進み、次回はそこから再開する。

開始・継続指定（cursor / after / start は相互排他。2つ以上の指定は400）:

  • 指定なし（mode省略またはhistory）: historyを先頭から開始
  • start=now（mode省略またはincremental）: 現在末尾のincremental checkpointだけを返す
  • after=evt_ID（mode省略またはincremental）: 自組織eventの位置からincrementalを開始
  • cursor: cursor内部のmodeを継続（mode併記は一致必須。暗黙に変換しない）
  • mode=incrementalのみ／mode=historyとafter・startの併用: 400 VALIDATION_ERROR

cursorは組織・mode・位置・watch_target_id絞り込みに束縛され、改竄や流用は400（先頭へ黙って戻さない）。回収済みcheckpointとして保存するのはincrementalのnext_cursorだけ。両モードともstream sequenceの昇順。historyではorder省略またはascを受け付け、初回・history cursorでの継続とも同じ順序で返す。incrementalではorderを省略する（start=now・after・incremental cursorとの併用はascを含め指定すると400 VALIDATION_ERROR）。modeを省略した場合も同じ制約が適用される。orderのdesc・不正値は両モードとも400。order=descはdashboard専用で受け付けない（dashboard履歴のdesc cursorも400）。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: 最短A: APIキーで変更イベントを取得する / pull補完・停止・解約

パラメータ

nameintyperequireddescription
orderquerystring (asc)Nohistory専用。ascのみ指定可（省略時もstream sequenceの昇順）。incrementalではorderを省略する（start=now・after・incremental cursorとの併用はascを含め指定すると400）。desc・不正値も400 VALIDATION_ERROR
modequerystring (history | incremental)No取得モード。省略時は開始指定から解決する（指定なし=history、after/start=now=incremental、cursor=cursor内部のmode）。cursorと併記する場合は一致必須
cursorquerystringNo前ページのnext_cursor（opaque・署名付き）。cursor / after / start は相互排他。cursor内部のmodeを継続し、組織・watch_target_id絞り込み・modeに束縛される（改竄・流用・mode不一致は400）
afterquerystringNoこの自組織eventの直後からincrementalを開始する。cursor / after / start は相互排他。mode=historyとの併用は400、失効中は410 CHANGE_EVENT_EXPIRED、他組織・不存在は404
startquerystring (now)Nonowのみ。現在末尾のincremental checkpointから購読を開始する。cursor / after / start は相互排他。mode=historyとの併用は400
limitqueryintegerNo1ページの件数（1〜100）。先頭ゼロ・符号・小数・指数表記は400
watch_target_idquerystringNo監視対象（wt_ ID）で絞り込む。存在・所有は検証せず、該当なしは空ページ。incrementalの欠落判定は絞り込みに関わらず組織全体で行う

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/change-events'

レスポンス例（200）

変更イベント一覧

新着なしのincremental（空でもnext_cursorは走査済み位置へ進む）

{
  "continuity_guaranteed": true,
  "data": [],
  "has_more": false,
  "item": "change_event",
  "limit": 100,
  "links": {
    "docs": "https://bango-api.jp/docs#change_events_list",
    "next": null,
    "self": "https://api.bango-api.jp/v1/change-events?cursor=cm1.aW5jcmVtZW50YWw.c2ln"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "mode": "incremental",
  "next_after": null,
  "next_cursor": "cm1.ZW1wdHk.c2ln",
  "object": "list",
  "schema_version": "2026-08"
}

history（保持中履歴のbest-effort列挙。continuity_guaranteed=false・next_after=null）

{
  "continuity_guaranteed": false,
  "data": [
    {
      "data": {
        "changes": [
          {
            "current": "4710826",
            "path": "/company/address/post_code",
            "previous": "4718571"
          }
        ],
        "current": {
          "company": {
            "active": true,
            "address": {
              "city": "豊田市",
              "city_code": "23211",
              "city_en": null,
              "full": "愛知県豊田市トヨタ町１番地",
              "image_id": null,
              "post_code": "4710826",
              "prefecture": "愛知県",
              "prefecture_code": "23",
              "prefecture_en": null,
              "street": "トヨタ町１番地"
            },
            "address_outside": null,
            "assignment_date": "2015-10-05",
            "closure": null,
            "corporate_number": "1180301018771",
            "invoice": {
              "cancel_date": null,
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T1180301018771",
              "valid": true
            },
            "kind": "株式会社",
            "kind_code": "301",
            "name": "トヨタ自動車株式会社",
            "name_en": null,
            "name_image_id": null,
            "name_kana": "トヨタジドウシャ",
            "revision": {
              "change_cause": null,
              "change_date": null,
              "correct": null,
              "latest": null,
              "process": null,
              "published_date": null,
              "sequence_number": null
            },
            "search_excluded": null,
            "updated_at": "2026-09-30"
          },
          "invoice": {
            "active": true,
            "address": {
              "city": "豊田市",
              "city_code": "23211",
              "city_en": null,
              "full": "愛知県豊田市トヨタ町１番地",
              "image_id": null,
              "post_code": "4710826",
              "prefecture": "愛知県",
              "prefecture_code": "23",
              "prefecture_en": null,
              "street": "トヨタ町１番地"
            },
            "address_inside": null,
            "address_outside": null,
            "address_request": null,
            "assignment_date": "2015-10-05",
            "closure": null,
            "corporate_number": "1180301018771",
            "country": "domestic",
            "invoice": {
              "cancel_date": null,
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T1180301018771",
              "valid": true
            },
            "kind": "corporation",
            "name": "トヨタ自動車株式会社",
            "name_en": null,
            "name_kana": "トヨタジドウシャ",
            "popular_name": null,
            "revision": null,
            "trade_name": null,
            "updated_at": "2021-10-28"
          }
        },
        "previous": null,
        "transition": null
      },
      "detected_at": "2026-09-30T02:00:00Z",
      "effective_date": null,
      "id": "evt_ddc487b3-8af5-4c1f-b2fe-7d59ba5949da",
      "object": "change_event",
      "origin": "source_change",
      "resource": {
        "id": "1180301018771",
        "type": "company"
      },
      "schema_version": "2026-09",
      "snapshot_at": "2026-09-30T01:58:00Z",
      "source": {
        "name": "nta",
        "revision": null,
        "updated_at": "2026-09-30"
      },
      "subject": {
        "corporate_number": "1180301018771",
        "id": "sub_ee7b4514-902a-4c38-867f-3fd740e23489",
        "kind": "corporation",
        "registration_number": "T1180301018771",
        "version": "43"
      },
      "type": "company.updated"
    },
    {
      "data": {
        "changes": [
          {
            "current": false,
            "path": "/invoice/invoice/valid",
            "previous": true
          }
        ],
        "current": {
          "company": null,
          "invoice": {
            "active": null,
            "address": null,
            "address_inside": null,
            "address_outside": null,
            "address_request": null,
            "assignment_date": null,
            "closure": null,
            "corporate_number": null,
            "country": "domestic",
            "invoice": {
              "cancel_date": "2026-10-01",
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T0123456789012",
              "valid": false
            },
            "kind": "individual",
            "name": null,
            "name_en": null,
            "name_kana": null,
            "popular_name": null,
            "revision": null,
            "trade_name": null,
            "updated_at": null
          }
        },
        "previous": null,
        "transition": {
          "from": true,
          "reasons": [
            "cancel_date"
          ],
          "to": false
        }
      },
      "detected_at": "2026-10-01T00:05:00Z",
      "effective_date": "2026-10-01",
      "id": "evt_bf00d209-6170-472a-9b5e-53183ba76d5a",
      "object": "change_event",
      "origin": "effective_date",
      "resource": {
        "id": "T0123456789012",
        "type": "invoice"
      },
      "schema_version": "2026-09",
      "snapshot_at": "2026-09-30T15:00:00Z",
      "source": {
        "name": "nta",
        "revision": null,
        "updated_at": "2026-09-01"
      },
      "subject": {
        "corporate_number": null,
        "id": "sub_5d0c8f3e-7a21-4b6e-9f14-c2e8a7b3d615",
        "kind": "individual",
        "registration_number": "T0123456789012",
        "version": "7"
      },
      "type": "invoice.validity_changed"
    }
  ],
  "has_more": true,
  "item": "change_event",
  "limit": 2,
  "links": {
    "docs": "https://bango-api.jp/docs#change_events_list",
    "next": "https://api.bango-api.jp/v1/change-events?limit=2&cursor=cm1.aGlzdG9yeQ.c2ln",
    "self": "https://api.bango-api.jp/v1/change-events?limit=2"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "mode": "history",
  "next_after": null,
  "next_cursor": "cm1.aGlzdG9yeQ.c2ln",
  "object": "list",
  "schema_version": "2026-08"
}

incremental（checkpointからの連続性保証。next_after=返却末尾event）

{
  "continuity_guaranteed": true,
  "data": [
    {
      "data": {
        "changes": [
          {
            "current": null,
            "path": "/company",
            "previous": {
              "active": true,
              "address": {
                "city": "豊田市",
                "city_code": "23211",
                "city_en": null,
                "full": "愛知県豊田市トヨタ町１番地",
                "image_id": null,
                "post_code": "4710826",
                "prefecture": "愛知県",
                "prefecture_code": "23",
                "prefecture_en": null,
                "street": "トヨタ町１番地"
              },
              "address_outside": null,
              "assignment_date": "2015-10-05",
              "closure": null,
              "corporate_number": "1180301018771",
              "invoice": {
                "cancel_date": null,
                "country": "domestic",
                "expire_date": null,
                "found": true,
                "registered": true,
                "registration_date": "2023-10-01",
                "registration_number": "T1180301018771",
                "valid": true
              },
              "kind": "株式会社",
              "kind_code": "301",
              "name": "トヨタ自動車株式会社",
              "name_en": null,
              "name_image_id": null,
              "name_kana": "トヨタジドウシャ",
              "revision": {
                "change_cause": null,
                "change_date": null,
                "correct": null,
                "latest": null,
                "process": null,
                "published_date": null,
                "sequence_number": null
              },
              "search_excluded": null,
              "updated_at": "2026-09-30"
            }
          }
        ],
        "current": {
          "company": null,
          "invoice": {
            "active": true,
            "address": {
              "city": "豊田市",
              "city_code": "23211",
              "city_en": null,
              "full": "愛知県豊田市トヨタ町１番地",
              "image_id": null,
              "post_code": "4710826",
              "prefecture": "愛知県",
              "prefecture_code": "23",
              "prefecture_en": null,
              "street": "トヨタ町１番地"
            },
            "address_inside": null,
            "address_outside": null,
            "address_request": null,
            "assignment_date": "2015-10-05",
            "closure": null,
            "corporate_number": "1180301018771",
            "country": "domestic",
            "invoice": {
              "cancel_date": null,
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T1180301018771",
              "valid": true
            },
            "kind": "corporation",
            "name": "トヨタ自動車株式会社",
            "name_en": null,
            "name_kana": "トヨタジドウシャ",
            "popular_name": null,
            "revision": null,
            "trade_name": null,
            "updated_at": "2021-10-28"
          }
        },
        "previous": {
          "company": {
            "active": true,
            "address": {
              "city": "豊田市",
              "city_code": "23211",
              "city_en": null,
              "full": "愛知県豊田市トヨタ町１番地",
              "image_id": null,
              "post_code": "4710826",
              "prefecture": "愛知県",
              "prefecture_code": "23",
              "prefecture_en": null,
              "street": "トヨタ町１番地"
            },
            "address_outside": null,
            "assignment_date": "2015-10-05",
            "closure": null,
            "corporate_number": "1180301018771",
            "invoice": {
              "cancel_date": null,
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T1180301018771",
              "valid": true
            },
            "kind": "株式会社",
            "kind_code": "301",
            "name": "トヨタ自動車株式会社",
            "name_en": null,
            "name_image_id": null,
            "name_kana": "トヨタジドウシャ",
            "revision": {
              "change_cause": null,
              "change_date": null,
              "correct": null,
              "latest": null,
              "process": null,
              "published_date": null,
              "sequence_number": null
            },
            "search_excluded": null,
            "updated_at": "2026-09-30"
          },
          "invoice": {
            "active": true,
            "address": {
              "city": "豊田市",
              "city_code": "23211",
              "city_en": null,
              "full": "愛知県豊田市トヨタ町１番地",
              "image_id": null,
              "post_code": "4710826",
              "prefecture": "愛知県",
              "prefecture_code": "23",
              "prefecture_en": null,
              "street": "トヨタ町１番地"
            },
            "address_inside": null,
            "address_outside": null,
            "address_request": null,
            "assignment_date": "2015-10-05",
            "closure": null,
            "corporate_number": "1180301018771",
            "country": "domestic",
            "invoice": {
              "cancel_date": null,
              "country": "domestic",
              "expire_date": null,
              "found": true,
              "registered": true,
              "registration_date": "2023-10-01",
              "registration_number": "T1180301018771",
              "valid": true
            },
            "kind": "corporation",
            "name": "トヨタ自動車株式会社",
            "name_en": null,
            "name_kana": "トヨタジドウシャ",
            "popular_name": null,
            "revision": null,
            "trade_name": null,
            "updated_at": "2021-10-28"
          }
        },
        "transition": null
      },
      "detected_at": "2026-10-02T02:00:00Z",
      "effective_date": null,
      "id": "evt_a0be2cc0-0ab2-4b1b-95de-1094ce08d7d7",
      "object": "change_event",
      "origin": "source_change",
      "resource": {
        "id": "1180301018771",
        "type": "company"
      },
      "schema_version": "2026-09",
      "snapshot_at": "2026-10-02T01:58:00Z",
      "source": {
        "name": "nta",
        "revision": null,
        "updated_at": "2026-10-02"
      },
      "subject": {
        "corporate_number": "1180301018771",
        "id": "sub_ee7b4514-902a-4c38-867f-3fd740e23489",
        "kind": "corporation",
        "registration_number": "T1180301018771",
        "version": "44"
      },
      "type": "company.deleted"
    }
  ],
  "has_more": false,
  "item": "change_event",
  "limit": 100,
  "links": {
    "docs": "https://bango-api.jp/docs#change_events_list",
    "next": null,
    "self": "https://api.bango-api.jp/v1/change-events?cursor=cm1.c3RhcnQ.c2ln"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "mode": "incremental",
  "next_after": "evt_a0be2cc0-0ab2-4b1b-95de-1094ce08d7d7",
  "next_cursor": "cm1.aW5jcmVtZW50YWw.c2ln",
  "object": "list",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORquery不正（VALIDATION_ERROR。排他違反・mode不一致・cursor改竄/流用・書式・orderのdesc・不正値・history以外のorder指定（ascを含む））
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
404NOT_FOUNDafterのeventが自組織に存在しない（NOT_FOUND）
410CHANGE_EVENT_EXPIRED / CHANGE_EVENT_HISTORY_GAPafterのevent失効（CHANGE_EVENT_EXPIRED）・incrementalの欠落検知（CHANGE_EVENT_HISTORY_GAP）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/change-events/{event_id}

変更イベント取得

x-api-key

自組織の変更イベントを1件返す。dataは保存時のevent本体で、event側のschema_versionはRESTエンベロープのschema_versionと独立。

Freeから利用できます。上限はプランごとに異なります。認証は x-api-key で、各リクエストは月間APIコールに計上されます。

関連ガイド: イベントの種類

パラメータ

nameintyperequireddescription
event_idpathstringYes変更イベントID（evt_）。書式不正は400

リクエスト例

curl -H 'x-api-key: YOUR_API_KEY' \
  'https://api.bango-api.jp/v1/change-events/YOUR_EVENT_ID'

レスポンス例（200）

変更イベント

個人事業者の取消日到来による無効化

{
  "data": {
    "data": {
      "changes": [
        {
          "current": false,
          "path": "/invoice/invoice/valid",
          "previous": true
        }
      ],
      "current": {
        "company": null,
        "invoice": {
          "active": null,
          "address": null,
          "address_inside": null,
          "address_outside": null,
          "address_request": null,
          "assignment_date": null,
          "closure": null,
          "corporate_number": null,
          "country": "domestic",
          "invoice": {
            "cancel_date": "2026-10-01",
            "country": "domestic",
            "expire_date": null,
            "found": true,
            "registered": true,
            "registration_date": "2023-10-01",
            "registration_number": "T0123456789012",
            "valid": false
          },
          "kind": "individual",
          "name": null,
          "name_en": null,
          "name_kana": null,
          "popular_name": null,
          "revision": null,
          "trade_name": null,
          "updated_at": null
        }
      },
      "previous": null,
      "transition": {
        "from": true,
        "reasons": [
          "cancel_date"
        ],
        "to": false
      }
    },
    "detected_at": "2026-10-01T00:05:00Z",
    "effective_date": "2026-10-01",
    "id": "evt_bf00d209-6170-472a-9b5e-53183ba76d5a",
    "object": "change_event",
    "origin": "effective_date",
    "resource": {
      "id": "T0123456789012",
      "type": "invoice"
    },
    "schema_version": "2026-09",
    "snapshot_at": "2026-09-30T15:00:00Z",
    "source": {
      "name": "nta",
      "revision": null,
      "updated_at": "2026-09-01"
    },
    "subject": {
      "corporate_number": null,
      "id": "sub_5d0c8f3e-7a21-4b6e-9f14-c2e8a7b3d615",
      "kind": "individual",
      "registration_number": "T0123456789012",
      "version": "7"
    },
    "type": "invoice.validity_changed"
  },
  "links": {
    "docs": "https://bango-api.jp/docs#change_events_get",
    "self": "https://api.bango-api.jp/v1/change-events/evt_bf00d209-6170-472a-9b5e-53183ba76d5a"
  },
  "meta": {
    "quota": {
      "api_requests": {
        "limit": 60000,
        "remaining": 59987,
        "unlimited": false
      },
      "batch_rows": null
    },
    "rate_limit": {
      "limit": 6000,
      "remaining": 599,
      "reset": "2026-05-14T02:31:00Z",
      "unlimited": false
    },
    "source": {
      "name": "nta",
      "updated_at": null
    }
  },
  "object": "change_event",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORevent_id書式不正（VALIDATION_ERROR）
401UNAUTHORIZEDAPIキー未指定・不正（UNAUTHORIZED）。X-RateLimit-*/X-Quota-*は送出しない
403FORBIDDEN閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND他組織・不存在（NOT_FOUND）
410CHANGE_EVENT_EXPIRED保持期限切れ（CHANGE_EVENT_EXPIRED）
429QUOTA_EXCEEDED / RATE_LIMIT_EXCEEDEDレート制限・クォータ超過（RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

Webhook Control plane

ログイン利用者のJWTで呼ぶ、Webhook受信先と配送の管理です。変更監視画面の「Webhook」タブも同じ操作を使います。

次の4つは、変更監視画面（Dashboard）が使う閲覧用APIです。ログイン利用者の Authorization: Bearer <JWT> で認証し、月間APIコールを消費しません。仕様は OpenAPI仕様 を参照します。

GET/v1/change-monitoring/events/{event_id}/deliveries

変更イベントのdelivery一覧（Dashboard）

GET/v1/change-monitoring/history

変更イベント履歴（Dashboard・history専用）

GET/v1/change-monitoring/summary

変更監視の利用状況サマリー（Dashboard）

GET/v1/change-monitoring/watch-targets

監視対象一覧（Dashboard）

GET/v1/webhook-endpoints

webhook endpoint一覧

Bearer JWT

組織のendpointを全件返す（paginationなし・metaなし）。secretはsecret_fingerprintのみ。全ロールが閲覧できる。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 最短B: Webhookで変更イベントを受け取る

パラメータ

なし

リクエスト例

curl -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints'

レスポンス例（200）

endpoint一覧

組織のendpoint全件（paginationなし）

{
  "data": [
    {
      "capacity_warning": null,
      "config_revision": 1,
      "created_at": "2026-09-20T01:00:00Z",
      "disabled_reason": null,
      "event_types": [
        "company.updated",
        "company.closed",
        "company.deleted",
        "invoice.validity_changed"
      ],
      "health": "healthy",
      "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
      "last_failure_at": "2026-10-01T00:06:03Z",
      "last_success_at": "2026-09-30T02:00:02Z",
      "last_test_succeeded_at": "2026-09-20T01:05:00Z",
      "recovery_required": false,
      "secret_fingerprint": "whfp_00000000000000a1",
      "status": "active",
      "updated_at": "2026-09-20T01:05:00Z",
      "url": "https://hooks.example.jp/bango/webhooks",
      "url_revision": 1
    },
    {
      "capacity_warning": null,
      "config_revision": 2,
      "created_at": "2026-09-10T00:00:00Z",
      "disabled_reason": null,
      "event_types": [
        "invoice.updated",
        "invoice.deleted"
      ],
      "health": null,
      "id": "whep_8de5a579-417b-45ce-a690-8c98e88b988f",
      "last_failure_at": null,
      "last_success_at": null,
      "last_test_succeeded_at": null,
      "recovery_required": false,
      "secret_fingerprint": "whfp_00000000000000b1",
      "status": "paused",
      "updated_at": "2026-09-12T00:00:00Z",
      "url": "https://hooks.example.jp/bango/audit",
      "url_revision": 1
    }
  ],
  "item": "webhook_endpoint",
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_list",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints"
  },
  "object": "list",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDEN削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints

webhook endpoint作成

Bearer JWT

url・event_types（非空・既知enum・重複は除去）を指定しactiveで作成する。201応答のdata.secretが署名secret全文を得る唯一の機会で、以後の取得系はsecret_fingerprintのみ返す。secretを含む応答はキャッシュさせない。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 最短B: Webhookで変更イベントを受け取る / watch登録と署名検証のサンプル

パラメータ

なし

リクエスト例

# data.secret は一度しか返りません。安全な保管先へ保存し、ログや標準出力に出さないでください。
curl -X POST -H 'Authorization: Bearer <JWT>' -H 'Content-Type: application/json' \
  -d '{"event_types":["company.updated","company.closed","company.deleted","invoice.validity_changed"],"url":"https://hooks.example.jp/bango/webhooks"}' \
  'https://api.bango-api.jp/v1/webhook-endpoints'

レスポンス例（201）

作成したendpointと署名secret全文

作成直後（secret全文はこの応答とrotate-secretのみ）

{
  "data": {
    "capacity_warning": null,
    "config_revision": 1,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.updated",
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": "healthy",
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": null,
    "last_success_at": null,
    "last_test_succeeded_at": null,
    "recovery_required": false,
    "secret": "whsec_ex+mple/Created/WebhookSecret/NotARealKey0A=",
    "secret_fingerprint": "whfp_00000000000000a1",
    "status": "active",
    "updated_at": "2026-09-20T01:00:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_create",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORbody不正（VALIDATION_ERROR）
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
409RESOURCE_LIMIT_EXCEEDEDactive endpoint数の上限超過（RESOURCE_LIMIT_EXCEEDED。resource_limit.resource=webhook_endpoints）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/webhook-endpoints/{id}

webhook endpoint取得

Bearer JWT

endpointを1件返す。secretはsecret_fingerprintのみ。全ロールが閲覧できる。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 最短B: Webhookで変更イベントを受け取る

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

curl -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID'

レスポンス例（200）

endpoint

配送中のendpoint（secretは指紋のみ）

{
  "data": {
    "capacity_warning": null,
    "config_revision": 1,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.updated",
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": "healthy",
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": "2026-10-01T00:06:03Z",
    "last_success_at": "2026-09-30T02:00:02Z",
    "last_test_succeeded_at": "2026-09-20T01:05:00Z",
    "recovery_required": false,
    "secret_fingerprint": "whfp_00000000000000a1",
    "status": "active",
    "updated_at": "2026-09-20T01:05:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_get",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDEN削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

PATCH/v1/webhook-endpoints/{id}

webhook endpoint更新

Bearer JWT

url・event_typesの少なくとも一方を更新する（statusは変更不可）。URL変更は安全性を再検証し、disabled/goneをactiveへ戻さない。変更でconfig_revisionが進み、成功済みtest受領は無効になる。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 通常イベントの受信・重複・再送

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

curl -X PATCH -H 'Authorization: Bearer <JWT>' -H 'Content-Type: application/json' \
  -d '{"event_types":["company.closed","company.deleted","invoice.validity_changed"]}' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID'

レスポンス例（200）

更新後のendpoint

event_types更新（config_revisionが進みtest受領は無効化）

{
  "data": {
    "capacity_warning": null,
    "config_revision": 2,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": "healthy",
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": "2026-10-01T00:06:03Z",
    "last_success_at": "2026-09-30T02:00:02Z",
    "last_test_succeeded_at": null,
    "recovery_required": false,
    "secret_fingerprint": "whfp_00000000000000a1",
    "status": "active",
    "updated_at": "2026-10-02T00:00:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_patch",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORbody不正・空更新（VALIDATION_ERROR）
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

DELETE/v1/webhook-endpoints/{id}

webhook endpoint削除

Bearer JWT

endpointを削除し204（bodyなし）を返す。削除済みendpointへの再DELETEも204を返す（冪等）。未配送のdeliveryは配送されない。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織は404。削除済みへの再DELETEは204（冪等）

リクエスト例

curl -X DELETE -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID'

レスポンス例（204）

削除済み（bodyなし）。削除済みへの再DELETEも204（冪等）

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・不存在（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints/{id}/pause

webhook endpoint一時停止

Bearer JWT

activeのendpointを一時停止する（request bodyなし）。停止中はdeliveryを送らない。既にpausedなら何も変更せず現在のendpointを200で返す。disabled/goneは409。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

curl -X POST -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/pause'

レスポンス例（200）

停止後のendpoint

一時停止（healthはactive時のみ）

{
  "data": {
    "capacity_warning": null,
    "config_revision": 2,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.updated",
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": null,
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": "2026-10-01T00:06:03Z",
    "last_success_at": "2026-09-30T02:00:02Z",
    "last_test_succeeded_at": null,
    "recovery_required": false,
    "secret_fingerprint": "whfp_00000000000000a1",
    "status": "paused",
    "updated_at": "2026-10-02T00:00:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_pause",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
409WEBHOOK_ENDPOINT_NOT_ACTIVEdisabled/gone（WEBHOOK_ENDPOINT_NOT_ACTIVE）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints/{id}/resume

webhook endpoint再開

Bearer JWT

paused/disabled/goneのendpointを再開する（request bodyなし）。通常のpausedはtest不要。recovery_required=trueのpausedとsecurity_blocked以外のdisabledは、現在のconfig_revisionで成功したtest受領が必要。goneとdisabled_reason=security_blockedのdisabledは、その状態になった後にPATCHでurlを変更し（url_revisionが進む）、次に現在のconfig_revisionでtestを成功させ、最後にresumeする。PATCHはconfig_revisionを進めて既存のtest受領を無効にするため、testはURL変更の後に行う。過去のdeliveryは自動再開しない。予約済みdowngradeの発効後に枠を超える場合はcapacity_warningを返す。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: pull補完・停止・解約

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

curl -X POST -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/resume'

レスポンス例（200）

再開後のendpoint

再開（予約済みdowngrade後に枠を超える場合のwarning付き）

{
  "data": {
    "capacity_warning": {
      "active_endpoints": 2,
      "effective_at": "2026-11-01T00:00:00Z",
      "pending_plan_code": "starter",
      "target_limit": 1
    },
    "config_revision": 3,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.updated",
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": "healthy",
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": null,
    "last_success_at": null,
    "last_test_succeeded_at": null,
    "recovery_required": false,
    "secret_fingerprint": "whfp_00000000000000a1",
    "status": "active",
    "updated_at": "2026-10-03T00:00:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_resume",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
409WEBHOOK_ENDPOINT_RECOVERY_REQUIRED / RESOURCE_LIMIT_EXCEEDEDactive endpoint数の上限超過（RESOURCE_LIMIT_EXCEEDED）・再開条件の未充足（WEBHOOK_ENDPOINT_RECOVERY_REQUIRED。gone/security_blockedでその後のURL変更がない、または現在のconfig_revisionで成功したtest受領がない）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints/{id}/rotate-secret

署名secretのrotation

Bearer JWT

mode=gracefulは旧secretを24時間併存させ、immediateは即時に新secretだけへ切り替える。200応答のdata.secretが新secret全文を得る唯一の機会。secretを含む応答はキャッシュさせない。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 通常イベントの受信・重複・再送 / watch登録と署名検証のサンプル

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

# data.secret は一度しか返りません。安全な保管先へ保存し、ログや標準出力に出さないでください。
curl -X POST -H 'Authorization: Bearer <JWT>' -H 'Content-Type: application/json' \
  -d '{"mode":"graceful"}' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/rotate-secret'

レスポンス例（200）

新しい署名secret全文を含むendpoint

graceful rotation（新secret全文はこの応答のみ）

{
  "data": {
    "capacity_warning": null,
    "config_revision": 2,
    "created_at": "2026-09-20T01:00:00Z",
    "disabled_reason": null,
    "event_types": [
      "company.updated",
      "company.closed",
      "company.deleted",
      "invoice.validity_changed"
    ],
    "health": "healthy",
    "id": "whep_df2f4bf1-4dd7-4266-9289-104897f7c993",
    "last_failure_at": "2026-10-01T00:06:03Z",
    "last_success_at": "2026-09-30T02:00:02Z",
    "last_test_succeeded_at": null,
    "recovery_required": false,
    "secret": "whsec_ex+mple/Rotated/WebhookSecret/NotARealKey0A=",
    "secret_fingerprint": "whfp_00000000000000a2",
    "status": "active",
    "updated_at": "2026-10-02T00:00:00Z",
    "url": "https://hooks.example.jp/bango/webhooks",
    "url_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_rotate_secret",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993"
  },
  "object": "webhook_endpoint",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORbody不正（VALIDATION_ERROR）
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
409SECRET_ROTATION_IN_PROGRESSrotation進行中（SECRET_ROTATION_IN_PROGRESS）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints/{id}/test

webhook test送信

Bearer JWT

現在の設定へ署名付きtest eventを1回送る（request bodyなし・自動retryなし・本番deliveryの試行回数は消費しない）。受信側の非2xx・DNS/TLS/timeout・安全でない宛先は200のtest結果（success=false）で返す。ただし安全でない宛先が確定し、送信中に設定が変わっていない場合は副作用としてendpointをdisabled（disabled_reason=security_blocked）へ停止し未claimのdeliveryをcancelする（再開はURL変更→test→resume）。recovery_eligibleは送信中に設定が変わっていない場合だけtrue。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 最短B: Webhookで変更イベントを受け取る / イベントの種類

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404

リクエスト例

curl -X POST -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/test'

レスポンス例（200）

test結果

test送信の結果（受信側の失敗も200のtest結果で返る）

{
  "data": {
    "duration_ms": 182,
    "error_code": null,
    "http_status": 204,
    "recovery_eligible": true,
    "success": true,
    "tested_config_revision": 1
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_endpoints_test",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993/test"
  },
  "object": "webhook_test",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・削除済み（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/webhook-endpoints/{id}/deliveries

delivery一覧

Bearer JWT

endpointのdeliveryを新しい順に返す（keyset cursor・offsetなし・metaなし）。宛先URL・secret・署名・接続先IPは含まない。全ロールが閲覧できる。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 通常イベントの受信・重複・再送

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404
limitqueryintegerNo1ページの件数（1〜100）
cursorquerystringNo前ページのnext_cursor（opaque）。書式不正・破損・別versionは400。クライアントは解釈・生成しない

リクエスト例

curl -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/deliveries'

レスポンス例（200）

delivery一覧

新しい順のdelivery一覧（next_cursorはhas_more時のみ）

{
  "data": [
    {
      "attempt_count": 2,
      "canceled_at": null,
      "created_at": "2026-10-01T00:05:01.537402Z",
      "delivered_at": null,
      "delivery_cycle": 1,
      "event_id": "evt_bf00d209-6170-472a-9b5e-53183ba76d5a",
      "id": "whd_a7f44d90-dc03-4757-9250-f459e3640f3f",
      "last_error_code": null,
      "last_status_code": 503,
      "next_attempt_at": "2026-10-01T00:10:03Z",
      "status": "retrying",
      "terminal_reason": null,
      "updated_at": "2026-10-01T00:06:03.118220Z"
    },
    {
      "attempt_count": 1,
      "canceled_at": null,
      "created_at": "2026-09-30T02:00:01.204118Z",
      "delivered_at": "2026-09-30T02:00:02.391027Z",
      "delivery_cycle": 1,
      "event_id": "evt_ddc487b3-8af5-4c1f-b2fe-7d59ba5949da",
      "id": "whd_435ca06f-26b3-4c6f-8778-a92ce544a124",
      "last_error_code": null,
      "last_status_code": 200,
      "next_attempt_at": null,
      "status": "delivered",
      "terminal_reason": null,
      "updated_at": "2026-09-30T02:00:02.391027Z"
    }
  ],
  "has_more": true,
  "item": "webhook_delivery",
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_deliveries_list",
    "next": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993/deliveries?limit=2&cursor=wd1.eyJjYSI6IjIwMjYtMDktMzBUMDI6MDA6MDEuMjA0MTE4WiIsImlkIjoiNDM1Y2EwNmYtMjZiMy00YzZmLTg3NzgtYTkyY2U1NDRhMTI0In0",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993/deliveries?limit=2"
  },
  "next_cursor": "wd1.eyJjYSI6IjIwMjYtMDktMzBUMDI6MDA6MDEuMjA0MTE4WiIsImlkIjoiNDM1Y2EwNmYtMjZiMy00YzZmLTg3NzgtYTkyY2U1NDRhMTI0In0",
  "object": "list",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORquery不正・cursorの書式不正/破損（VALIDATION_ERROR）
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDEN削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUNDendpointの書式不正・他組織・削除済み（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

GET/v1/webhook-endpoints/{id}/deliveries/{delivery_id}

delivery詳細

Bearer JWT

deliveryの状態と試行履歴（新しい順・attempt_cursorで継続）を返す。試行の診断情報はdiagnostics_retained_since以降のみ保持する。全ロールが閲覧できる。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 通常イベントの受信・重複・再送

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404
delivery_idpathstringYesdelivery ID（whd_）。書式不正・不存在は404
attempt_limitqueryintegerNo1ページの試行件数（1〜100）
attempt_cursorquerystringNo前ページのattempts_next_cursor（opaque）。書式不正・破損・別versionは400。クライアントは解釈・生成しない

リクエスト例

curl -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/deliveries/YOUR_DELIVERY_ID'

レスポンス例（200）

delivery詳細と試行履歴

再送待ちdeliveryと試行履歴（診断は30日保持）

{
  "attempts": [
    {
      "attempt_number": 2,
      "delivery_cycle": 1,
      "duration_ms": 812,
      "error_code": null,
      "finished_at": "2026-10-01T00:06:03.117904Z",
      "response_status": 503,
      "retry_after_at": null,
      "started_at": "2026-10-01T00:06:02.305511Z",
      "status": "failed"
    },
    {
      "attempt_number": 1,
      "delivery_cycle": 1,
      "duration_ms": 609,
      "error_code": null,
      "finished_at": "2026-10-01T00:05:03.090617Z",
      "response_status": 503,
      "retry_after_at": null,
      "started_at": "2026-10-01T00:05:02.481352Z",
      "status": "failed"
    }
  ],
  "attempts_has_more": false,
  "attempts_next_cursor": null,
  "data": {
    "attempt_count": 2,
    "canceled_at": null,
    "created_at": "2026-10-01T00:05:01.537402Z",
    "delivered_at": null,
    "delivery_cycle": 1,
    "event_id": "evt_bf00d209-6170-472a-9b5e-53183ba76d5a",
    "id": "whd_a7f44d90-dc03-4757-9250-f459e3640f3f",
    "last_error_code": null,
    "last_status_code": 503,
    "next_attempt_at": "2026-10-01T00:10:03Z",
    "status": "retrying",
    "terminal_reason": null,
    "updated_at": "2026-10-01T00:06:03.118220Z"
  },
  "diagnostics_retained_since": "2026-09-02T00:07:00Z",
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_deliveries_get",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993/deliveries/whd_a7f44d90-dc03-4757-9250-f459e3640f3f"
  },
  "object": "webhook_delivery",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
400VALIDATION_ERRORquery不正・cursorの書式不正/破損（VALIDATION_ERROR）
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDEN削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・不存在（NOT_FOUND）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。

POST/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay

delivery手動再送

Bearer JWT

deliveryを新しいdelivery cycleとして再送する（request bodyなし・attempt_countは0から）。owner/adminのみ。Bearer JWT（Dashboardセッション）で認証し、monthly api_requestsは消費しない。

Freeから利用できます。上限はプランごとに異なります。作成・更新・停止・削除などの書き込みはowner / adminのみ、閲覧は全ロールが行えます。認証はログイン利用者の Authorization: Bearer <JWT> で、月間APIコールを消費しません。組織ごとに毎分60リクエストのレート制限があります。

関連ガイド: 通常イベントの受信・重複・再送 / pull補完・停止・解約

パラメータ

nameintyperequireddescription
idpathstringYeswebhook endpoint ID（whep_）。書式不正・他組織・削除済みは404
delivery_idpathstringYesdelivery ID（whd_）。書式不正・不存在は404

リクエスト例

curl -X POST -H 'Authorization: Bearer <JWT>' \
  'https://api.bango-api.jp/v1/webhook-endpoints/YOUR_WEBHOOK_ENDPOINT_ID/deliveries/YOUR_DELIVERY_ID/replay'

レスポンス例（200）

再送を受け付けたdelivery

exhausted delivery の手動再送（新cycle）

{
  "data": {
    "attempt_count": 0,
    "canceled_at": null,
    "created_at": "2026-10-02T02:00:01.318204Z",
    "delivered_at": null,
    "delivery_cycle": 2,
    "event_id": "evt_a0be2cc0-0ab2-4b1b-95de-1094ce08d7d7",
    "id": "whd_38f8e91d-77e6-4992-a453-97075dec4df4",
    "last_error_code": null,
    "last_status_code": null,
    "next_attempt_at": "2026-10-05T09:00:00.214508Z",
    "status": "pending",
    "terminal_reason": null,
    "updated_at": "2026-10-05T09:00:00.214508Z"
  },
  "links": {
    "docs": "https://bango-api.jp/docs#webhook_deliveries_replay",
    "self": "https://api.bango-api.jp/v1/webhook-endpoints/whep_df2f4bf1-4dd7-4266-9289-104897f7c993/deliveries/whd_38f8e91d-77e6-4992-a453-97075dec4df4/replay"
  },
  "object": "webhook_delivery",
  "schema_version": "2026-08"
}

エラー（statusとProblem code）

statuscodedescription
401UNAUTHORIZEDBearer JWT未指定・不正・期限切れ（UNAUTHORIZED）
403FORBIDDENmemberロール、または削除済みアカウント（JWTが有効期限内でも）・所属organizationを1件に確定できない・閉鎖済みorganization（FORBIDDEN）
404NOT_FOUND書式不正・他組織・不存在（NOT_FOUND）
409WEBHOOK_DELIVERY_NOT_REPLAYABLE / WEBHOOK_ENDPOINT_NOT_ACTIVEendpointがactiveでない（WEBHOOK_ENDPOINT_NOT_ACTIVE）・再送できない状態（WEBHOOK_DELIVERY_NOT_REPLAYABLE）
410CHANGE_EVENT_EXPIRED対象eventの保持期限切れ（CHANGE_EVENT_EXPIRED）
429RATE_LIMIT_EXCEEDEDControl planeのレート制限超過（RATE_LIMIT_EXCEEDED）
503DEPENDENCY_UNAVAILABLE依存障害（DEPENDENCY_UNAVAILABLE）

各codeの意味と回復手順は エラーリファレンス を参照します。