法人番号APIをJSONで使う方法｜XMLからの変換と選択肢

結論から言うと、国税庁の法人番号システムWeb-APIは、JSONで応答する設定がありません。 応答形式はCSV（Shift-JISかUnicode）かXML（Unicode）の3種類です。

JSONで扱いたいときの方法は2つです。

1. XMLを受け取って、自分でJSONに変換する
2. JSONで返す別のAPIを使う

この記事では両方の方法と、変換するときの注意点を説明します。JSONで返すAPIの比較は法人番号APIの比較にまとめています。

国税庁APIの応答形式

ちなみに、インボイスWeb-API（適格請求書発行事業者公表システム）はJSONを選べます。法人番号のAPIだけがJSONに対応していない点に注意してください。

方法1：XMLを受け取ってJSONに変換する

JSONに変換するなら、項目名が付いているXML（type=12）を選ぶのが楽です。CSVは列の順番で意味を読み取る必要があり、項目が増えたときに壊れやすくなります。

Pythonの例

import json
import xml.etree.ElementTree as ET

FIELDS = {
    "corporateNumber": "corporate_number",
    "name": "name",
    "furigana": "name_kana",
    "prefectureName": "prefecture",
    "cityName": "city",
    "streetNumber": "street",
    "postCode": "post_code",
    "assignmentDate": "assignment_date",
    "closeDate": "close_date",
}


def xml_to_json(xml_bytes: bytes) -> str:
    root = ET.fromstring(xml_bytes)
    rows = [
        {key: (corp.findtext(tag) or None) for tag, key in FIELDS.items()}
        for corp in root.findall("corporation")
    ]
    return json.dumps(rows, ensure_ascii=False)

JavaScriptの例

import { XMLParser } from "fast-xml-parser";

// 数字の項目を数値にしないよう、すべて文字列として受け取る
const parser = new XMLParser({ parseTagValue: false });

export function xmlToJson(xml) {
  const corps = parser.parse(xml).corporations?.corporation ?? [];
  return JSON.stringify(Array.isArray(corps) ? corps : [corps]);
}

変換するときの4つの注意点

1. 番号を数値にしない

法人番号、郵便番号、都道府県コードは、数字だけでできていても文字列として扱います。数値にすると先頭の0が消えたり、言語によっては桁が落ちたりします。

2. 空の項目はnullにそろえる

XMLでは、値のない項目が空の要素で返ります。そのまま変換すると空文字になるので、null にそろえておくと、使う側で判定しやすくなります。

3. 1件のときに配列にならない

XMLをJSONに変換するライブラリの多くは、要素が1つしかないときに配列ではなくオブジェクトにします。件数によって形が変わらないように、必ず配列にそろえてください。

4. 外字の扱い

商号には、JIS第三・第四水準の文字を含むものがあります。Unicodeの形式を選べば文字は失われませんが、使う側のシステムが対応していない場合があります。国税庁は、これらの文字を第一・第二水準に置き換える対応表（JIS縮退マップ）を公開しています。

方法2：JSONで返すAPIを使う

最初からJSONで返す民間のAPIを使えば、変換の処理は要りません。たとえばBango API は、次のようなJSONを返します。

{
  "object": "company",
  "data": {
    "corporate_number": "1180301018771",
    "name": "トヨタ自動車株式会社",
    "name_kana": "トヨタジドウシャ",
    "address": {
      "prefecture": "愛知県",
      "city": "豊田市",
      "street": "トヨタ町１番地",
      "post_code": "4710826"
    },
    "invoice": { "registration_number": "T1180301018771", "valid": true }
  }
}

法人番号の情報とインボイスの登録状況が1つのJSONにまとまっているので、2つのAPIの応答を突き合わせる処理も要りません。

どちらを選ぶか

JSONで返すAPIの料金や機能の違いは、法人番号APIの比較で確認してください。

まとめ

国税庁の法人番号APIはJSONに対応していないので、XMLを受け取って変換するか、JSONで返すAPIを使います。変換するなら、番号を文字列のまま扱うこと、空の項目と件数の違いで形を変えないことを守れば、扱いやすいJSONになります。