{"openapi":"3.1.0","info":{"title":"jp-data-mcp API","version":"1.0.0","summary":"国税庁 法人番号 + 適格請求書発行事業者 公表データ API","description":"国税庁の公表データ(法人番号公表サイト / 適格請求書発行事業者公表サイト)を REST 経由で提供する API です。MCP (Model Context Protocol) エンドポイントは OAuth 2.1 + DCR を使うため、この OpenAPI スキーマには含まれていません。本サービスは国税庁によって保証されたものではありません。","contact":{"name":"Clantable","url":"https://clantable.com/products/jp-data-mcp"},"license":{"name":"Service Terms","url":"https://clantable.com/products/jp-data-mcp/terms"}},"servers":[{"url":"https://jp-data-mcp.clantable.app","description":"production"}],"security":[{"bearer":[]}],"tags":[{"name":"corporations","description":"法人番号 / 商号検索"},{"name":"invoices","description":"適格請求書発行事業者 (法人インボイス)"},{"name":"meta","description":"ヘルスチェック / フレッシュネス / 障害履歴 (認証不要)"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"jpm_...","description":"ダッシュボードで発行した REST API Key を `Authorization: Bearer jpm_...` で送信。REST エンドポイント (/api/v1/houjin/*, /api/v1/invoice/*) でのみ有効。MCP (/mcp) では使用不可 — そちらは OAuth 2.1 + DCR。"}},"schemas":{"ApiMeta":{"type":"object","required":["source"],"properties":{"source":{"type":"string","enum":["corporations","invoices","meta"],"description":"データソース種別"},"source_url":{"type":"string","description":"公式情報源 URL (国税庁公表サイト)。法的効力のある照会はここで行う。"},"fetched_at":{"type":"string","format":"date-time","description":"キャッシュ取得時刻 (ISO 8601)"},"coverage":{"type":"string","enum":["corporation_full","corporation_only","meta"],"description":"corporation_full=法人番号公表サイト全件 / corporation_only=法人インボイスのみ (個人事業主未収録) / meta=ヘルスチェック等"},"disclaimer":{"type":"string","description":"本データはキャッシュであり、法的効力は公式サイトで確認すべき旨の注記。"},"request_id":{"type":"string","description":"リクエスト ID。X-Request-Id レスポンスヘッダと同じ値。サポート問い合わせ時に提示。"}}},"Corporation":{"type":"object","properties":{"corporate_number":{"type":"string","example":"7010001008844"},"found":{"type":"boolean"},"name":{"type":"string"},"furigana":{"type":"string","nullable":true},"kind":{"type":"string","nullable":true},"address":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"post_code":{"type":"string","nullable":true},"outside":{"type":"string","nullable":true}}},"status":{"type":"object","properties":{"closed":{"type":"boolean"},"close_date":{"type":"string","nullable":true},"close_cause":{"type":"string","nullable":true},"successor_corporate_number":{"type":"string","nullable":true}}},"dates":{"type":"object","properties":{"assignment_date":{"type":"string","nullable":true},"update_date":{"type":"string","nullable":true},"change_date":{"type":"string","nullable":true}}},"source":{"type":"string"},"source_url":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"disclaimer":{"type":"string"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"CorporationSearchResult":{"type":"object","properties":{"query":{"type":"string"},"normalized_query":{"type":"string","nullable":true},"match_count":{"type":"integer"},"candidates":{"type":"array","items":{"type":"object","properties":{"corporate_number":{"type":"string"},"name":{"type":"string"},"furigana":{"type":"string","nullable":true},"prefecture_name":{"type":"string","nullable":true},"city_name":{"type":"string","nullable":true},"kind":{"type":"string","nullable":true}}}},"search_engine":{"type":"string","example":"fts5_trigram"},"source":{"type":"string"},"disclaimer":{"type":"string"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"Invoice":{"type":"object","properties":{"registration_number":{"type":"string","example":"T7010001008844"},"found":{"type":"boolean"},"registrant_type":{"type":"string","enum":["corporation","unincorporated","individual"],"description":"法人 / 人格のない社団 / 個人事業主"},"status":{"type":"string","enum":["active","revoked","expired"]},"is_active":{"type":"boolean"},"dates":{"type":"object","properties":{"registration_date":{"type":"string","nullable":true},"revocation_date":{"type":"string","nullable":true},"expiration_date":{"type":"string","nullable":true}}},"corporate_number":{"type":"string","nullable":true},"corporation":{"$ref":"#/components/schemas/Corporation","nullable":true},"note":{"type":"string","nullable":true},"source":{"type":"string"},"source_url":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"disclaimer":{"type":"string"},"external_lookup_url":{"type":"string","description":"当 DB に該当が無い場合に国税庁公式サイトの検索 URL を返す (404 のみ)"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","example":"invalid_format"},"message":{"type":"string"}}}},"parameters":{"XRequestId":{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$"},"description":"リクエスト ID。指定しない場合は Worker が UUID を発行し、X-Request-Id レスポンスヘッダ + _meta.request_id に同じ値を載せる。"}},"headers":{"XRequestIdResponse":{"description":"リクエスト ID。_meta.request_id と同じ値。Sentry 等の調査に使用。","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"リクエスト形式エラー","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API Key 不正または欠落","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"該当データなし","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"rate limit / daily cap / 月額予算超過","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"サーバ内部エラー","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/houjin/{bangou}":{"get":{"tags":["corporations"],"summary":"法人番号で法人を引く","operationId":"lookupHoujin","parameters":[{"name":"bangou","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{13}$"},"example":"7010001008844"},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"法人情報","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestIdResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Corporation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/houjin/search":{"get":{"tags":["corporations"],"summary":"商号 / フリガナで法人検索 (FTS5 trigram)","operationId":"searchHoujin","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":20},"description":"最大返却件数。検索は実際に返却した法人候補数が call 数として計上されます。"},{"name":"include_closed","in":"query","schema":{"type":"boolean","default":true}},{"name":"prefecture","in":"query","schema":{"type":"string"},"description":"都道府県名 (全角)"},{"name":"city","in":"query","schema":{"type":"string"},"description":"市区町村名 (全角)"},{"name":"prefecture_code","in":"query","schema":{"type":"string","pattern":"^[0-9]{2}$"},"description":"JIS X 0401 コード (2 桁)"},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"検索結果","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestIdResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorporationSearchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/invoice/{registrationNumber}":{"get":{"tags":["invoices"],"summary":"インボイス登録番号 (T+13 桁) の検証","operationId":"lookupInvoice","parameters":[{"name":"registrationNumber","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{13}$"},"example":"T7010001008844"},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"インボイス登録情報","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestIdResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"当 DB に該当無し (個人事業主・人格のない社団は未収録)。_meta.coverage=\"corporation_only\" / external_lookup_url を含む。","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestIdResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/healthz":{"get":{"tags":["meta"],"summary":"ヘルスチェック + データ取込フレッシュネス","operationId":"healthz","security":[],"responses":{"200":{"description":"ok / stale"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/freshness":{"get":{"tags":["meta"],"summary":"データ取込フレッシュネス (顧客向け公開 API) [BETA]","description":"⚠️ **BETA**: 本エンドポイントは正式提供前の機能です。レスポンス形式やキャッシュ仕様は予告なく変更される場合があります (利用規約 第15条)。\n\ncorporations / invoices それぞれの最新成功取込の日付・件数を返す。認証不要、CORS *、5 分キャッシュ。","operationId":"getFreshness","security":[],"x-beta":true,"responses":{"200":{"description":"直近の取込状況","content":{"application/json":{}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/incidents/recent":{"get":{"tags":["meta"],"summary":"過去 N 日の障害履歴 (公開ステータスページ用、認証不要) [BETA]","description":"⚠️ **BETA**: 本エンドポイントは正式提供前の機能です。レスポンス形式は予告なく変更される場合があります (利用規約 第15条)。","operationId":"listIncidents","security":[],"x-beta":true,"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":90,"minimum":1,"maximum":365}}],"responses":{"200":{"description":"incident リスト","content":{"application/json":{}}}}}}}}