국세청 법인번호 Web-API를 AI 에이전트에서 호출할 때 빠지기 쉬운 5가지 함정 — 공식 데이터를 AI 네이티브하게 사용하는 설계

본 기사는 Zenn 버전(URL은 #11 공개 후 추가)과 동일한 저자, 동일한 회사, 동일한 API를 다루지만, Qiita의 업무계 일본인 엔지니어 계층에 맞춰 표현을 최적화했습니다. 코드와 결론은 동일하며, "AI 에이전트에게 법인번호를 조회하게 하고 싶다 → 국세청의 공식 Web-API가 있다면 직접 호출하면 된다"라고 생각하고 구현에 들어가면 확실히 막히게 되는 구조를, 공식 사양의 실질적인 검증(verify)을 바탕으로 5가지 함정으로 정리했습니다. 지난 #10(B2B 4대 identifier hub 설계)에서 주소·법인번호·인명·날짜의 canonical hub 분할을 다루었으며, 본 기사는 그 4번째인 「법인번호」의

공식 데이터 source를 AI agent로부터 사용할 때의 실무적인 함정에 초점을 맞춥니다.

• 국세청은 법인번호의 공식 Web-API(법인번호 시스템 Web-API 기능)를 무상으로 제공하고 있다. "공식이 있다면 AI 에이전트에서 직접 호출하면 된다"는 언뜻 맞지만, AI agent의 연속 호출을 전제로 한 설계가 되어 있지 않기 때문에 구현 시 확실히 막힌다. - 구체적인 함정은 5가지:
  (1) 애플리케이션 ID의 사전 신청이 필수적(AI가 self-serve 할 수 없음), (2) 응답이 XML / CSV(Shift-JIS 포함)이며 JSON이 아님, (3) 1회 요청당 최대 10건이며 이름 검색 기능이 약함, (4) 출처 명시 의무(이용약관 제6조)를 AI가 누락하면 라이선스 위반, (5) 업종 코드나 표기 불일치 정규화(normalization)가 제공되지 않음 - 근본 원인은, 공식 Web-API가 「벌크 다운로드 + 인간이 사전에 신청하여 사용」을 전제로 설계되어 있어, AI agent가 1개 태스크에서 10~50회 연쇄 호출하는 이용 형태를 상정하지 않았기 때문이다. - 해결책은, 공식 데이터를 source로 하되 AI 네이티브한 wrapper API(REST/JSON · 출처 자동 포함 · 표기 불일치 정규화 · OpenAPI 3.1로 AI agent로부터 1개의 URL로 통합)를 사이에 두는 것이다. Shirabe 패밀리의 4번째인 Shirabe Corporation API는 2026년 6월 후반 출시 예정이며, 이 설계를 구현하고 있다. - 본 기사는 공식 오픈 데이터를 AI agent로부터 실용하기 위한 설계 패턴으로서, 공식 Web-API의 제약과 그 위에 무엇을 얹어야 하는지를 제시한다.

• AI 에이전트에게 일본의 법인 정보(법인번호 · 상호 · 소재지)를 조회하게 하고 싶은 개발자

• 국세청의 공식 Web-API를 한 번 호출해 보고 "이것을 AI가 연속해서 사용하기는 어렵겠구나"라고 느낀 분

• B2B SaaS / CRM / 신용 조사 / 영업 backend에서 법인 마스터를 LLM이 처리하도록 하려는 분

• "공식 오픈 데이터가 있는데 왜 wrapper가 필요한가"를 설계 판단으로서 정리하고 싶은 분

법인번호는 국세청이 1법인 1번호로 부여하는 13자리(체크 디지트 = 첫 번째 자리가 mod 9)의 identifier로, 약 500만 개 기업이 대상이다. 상호 · 본점 소재지 · 변경 이력이 공개되어 있으며, 이용은 원칙적으로 무상이다. 공식 취득 경로는 두 가지가 있다.

경로	개요	인증	데이터 범위
경로 1: Web-API	`https://api.houjin-bangou.nta.go.jp/{version}/{num	diff	name}`
경로 2: 다운로드	공표 사이트에서 월간 전체 + 일간 차분	인증 불필요	CSV / XML(Shift-JIS / Unicode 선택)

"공식이 있다면 직접 Web-API를 호출하여 AI가 법인번호를 조회할 수 있다" —— 이 발상으로 구현에 들어가면, 다음 5가지에서 차례대로 막히게 된다.

Web-API(경로 1)를 사용하려면, 사전에 애플리케이션 ID를 신청하여 발급받아야 한다. 이는 URL 파라미터 id에 실어서 매 요청마다 보내야 한다.

# 국세청 Web-API의 원시 호출 (version 4, 법인번호 lookup)
curl "https://api.houjin-bangou.nta.go.jp/4/num?id=APPLICATION_ID&number=1234567890123&type=12"
# ^^^^^^^^^^^^^ 사전 신청이 필요함

AI 에이전트 (AI agent)의 설계 사상은 "인간의 사전 절차 없이, 에이전트가 필요해진 순간에 외부 리소스에 도달하는 것"에 있다. 그런데 Web-API는 인간이 신청 양식을 거쳐 ID를 취득하는 단계가 끼어들기 때문에, AI 에이전트의 자율적 탐색 (discovery) → 즉시 이용 경로에 올라타지 못한다. 이는 "AI가 알아서 사용하기 시작하는" 설계의 정반대에 있다.

Web-API의 응답 형식은 CSV 또는 XML (type 파라미터로 지정)이다. CSV는 Shift-JIS와 UTF-8 중 선택해야 한다. JSON은 제공되지 않는다.

# Web-API의 CSV 응답 (발췌 이미지). 컬럼은 고정 순서이며 헤더 없음
"1234567890123","01","...","주식회사 샘플","...","도쿄도 미나토구","롯폰기 6-10-1",...

AI 에이전트 런타임 (AI agent runtime: OpenAI Function Calling / Anthropic Tool Use / Gemini Function Calling)은 JSON을 도구 (tool) 출력으로서 전달받는 것을 전제로 한다. XML / CSV를 받게 되면 다음과 같은 문제가 발생한다:

• LLM에게 파싱 (parse)을 맡긴다 → 컬럼 위치를 오인하거나, Shift-JIS의 글자 깨짐 사고 (Math.max적인 인코딩 지뢰) 발생
• 직접 XML/CSV → JSON 변환 계층을 작성한다 → 결국 래퍼 (wrapper)를 직접 만들게 된다

"공식 API를 직접 호출하면 중간 계층이 필요 없을 것"이라고 생각했지만, 문자 코드와 포맷 변환을 위한 중간 계층을 스스로 작성해야 하는 상황에 처하게 된다.

Web-API의 실시간 조회 (lookup)는 1회 요청당 최대 10건이다. AI 에이전트는 한 가지 태스크에서 고객 리스트 수백 건을 명의 대조 (matching)하는 등의 연쇄·벌크 (bulk) 이용을 전제로 하므로, 10건 제한은 실무에 맞지 않는다. 또한 Web-API의 루트 (route)는 num (번호 → 정보) / diff (차분) / name (명칭·소재지 검색)에 국한되어 있어, 표기 불일치를 포함한 상호로부터의 명의 대조 ("(주)샘플", "주식회사 샘플", "샘플(주)"를 동일시하는 작업)에는 취약하다.

게다가 가동 및 레이트 (rate) 측면에서 HTTP 403 / 404 / 500 핸들링을 호출 측에서 항상 보유해야 하며, AI 에이전트의 연속 호출 시 무시할 수 없는 빈도로 발생한다.

법인번호 공표 사이트의 데이터 이용에는 출처 명시 의무가 있다 (이용 약관 제6조). 구체적으로는 다음과 같은 취지의 표기를 적절한 장소에 게시해야 한다.

이 서비스는 국세청 법인번호 시스템 Web-API 기능을 이용하여 취득한 정보를 바탕으로 작성되었으나, 서비스의 내용은 국세청에 의해 보증된 것이 아닙니다.

이 지점이 AI 에이전트 특유의 함정이 된다. LLM이 최종 답변을 생성할 때, 취득한 데이터만 사용하고 출처 표기를 누락하는 것이 빈번하게 발생한다. 주소 API에서 사용하는 국토교통성 ABR의 CC BY 4.0과 동일한 구조로, 출처를 전파하지 않으면 라이선스 의무 위반이 사이런트(silent)하게 발생한다. 출처는 "API 응답 내부에 구조화된 필드로 동봉되어, LLM이 이를 인용에 포함하도록 유도되는" 형태가 아니라면 실운용에서는 지켜지기 어렵다.

국세청 Web-API가 반환하는 것은 법인번호·상호·소재지·변경 이력이 중심이며, 업종 코드 (JSIC 등)는 제공되지 않는다. 또한 앞서 언급했듯이 상호의 표기 불일치 정규화 및 명의 대조는 직접 수행해야 한다. B2B 레코드 처리에서 실제로 원하는 것은 "주식회사 샘플을 정규화하고, 13자리 번호를 부여하며, 주소와 연결하고, 가능하다면 업종으로 분류하는" 풍부해진 (enriched) 1개의 레코드이지만, 공식 Web-API는 그 소재의 일부를 XML/CSV로 반환할 뿐이며, 풍부화 (enrich) 작업은 전부 호출 측의 몫이 된다.

5가지 함정은 각각 별개의 불편함처럼 보이지만, 그 뿌리는 하나다. 국세청의 공식 경로는 "인간 또는 배치 처리 (Batch processing)가 사전에 신청하여, 월간 전체 데이터 + 차분 데이터를 다운로드하여 자체 DB에 가져오는" 방식의 벌크(Bulk) 및 인간 주도적 이용을 전제로 설계되어 있다. 이는 공공 데이터 제공 측면에서는 타당하지만,

• AI 에이전트 (AI agent)가 1개 태스크에서 10~50회
  **연쇄 호출 (Chained calls)**을 수행한다
• 사전 절차 없이
  필요한 순간에 도달한다
• JSON으로 받아서
  그대로 도구 (tool) 출력으로 흘려보낸다
• 출처를
  자동으로 인용에 전파한다

라는 AI 네이티브 (AI-native)한 이용 형태와는 설계 사상이 맞지 않는다. 공식 데이터의 품질은 최고지만, AI 에이전트 (AI agent)로부터의 직접 이용에는 래퍼 (wrapper)가 필요하다——이것이 구조적인 결론이다.

설계 패턴은 심플하다:

• 공식 데이터 (월간 전체 데이터 + 일간 차분 데이터, 인증이 필요 없는 다운로드 경로)를
  **신뢰할 수 있는 단일 출처 (source of truth)**로 가져온다
• 그 위에
  REST / JSON 기반의 AI 네이티브 API를 씌워, lookup (번호 → 정보) / search (명칭 → 번호 후보) / normalize (표기 불일치 정규화 + 번호 부여) / batch (벌크)를 제공한다
• 응답에
  출처 표기 (attribution)를 구조화된 필드로 동봉하여, LLM이 인용에 전파할 수 있는 형태로 만든다
• 모든 것을
  **하나의 OpenAPI 3.1 스펙 (spec)**으로 통합하여, AI 에이전트 (AI agent) 런타임 (runtime)에서 단 하나의 URL로 도구화 (tool化)할 수 있게 한다.

Shirabe 패밀리의 네 번째 모델인 Shirabe Corporation API가 바로 이 설계로 제작되었으며, 2026년 6월 하반기 출시 예정이다. 출시 후의 이용 이미지를 먼저 보여준다 (엔드포인트 URL은 출시 시 확정).

# 법인번호 → 법인정보 (JSON, 출처 표기 동봉) ※ 2026년 6월 하반기 출시 후
# curl https://shirabe.dev/api/v1/corporation/lookup \
# -H "Content-Type: application/json" \
...

반환되는 JSON의 이미지 (설계안):

{
"normalized_name": "株式会社サンプル",
"corporation_number": "1234567890123",
...
}

핵심은 출처 표기 (attribution)를 필수 응답 필드로 만드는 것이다. LLM이 스펙 (spec)을 학습하면 최종 답변에 출처를 자연스럽게 포함하게 되어,

함정 4(출처 의무 위반)를 구조적으로 방지한다. 주소 API에서 CC BY 4.0(국토교통성 ABR)에 대해 채택하고 있는 것과 동일한 수법을 국세청 데이터에도 적용한다.

OpenAPI 3.1을 하나의 URL로 공개해 두면, AI 에이전트 (AI agent) 런타임 (runtime)에서 그대로 도구화 (tool化)된다. Shirabe는 https://shirabe.dev/openapi.yaml (현재는 주소 + 달력 + 텍스트의 3개 허브 통합 스펙이며, 법인번호는 6월 하반기 출시 후 동일 스펙에 추가 예정)이다.

# OpenAPI 1 URL로부터 도구화 (프레임워크 없이). 법인번호 엔드포인트는 출시 후 동일 스펙에 추가
import httpx
spec = httpx.get("https://shirabe.dev/openapi.yaml").text
...

공식 Web-API를 직접 호출하는 구현과 비교했을 때, 애플리케이션 ID 신청, XML/CSV 파싱 (parsing), 문자 인코딩 처리, 10건 제한, 출처 전파, 표기 불일치 정규화를 호출 측에서 전부 제거할 수 있다.

관점	국세청 Web-API 직접 호출	AI 네이티브 wrapper (Shirabe Corporation API, 6월 하반기 예정)
인증	애플리케이션 ID 사전 신청 필수	AI agent에서 즉시 이용 (Free tier 가정)
...	normalize로 흡수
출처 전파	호출 측에서 수동 게시	attribution을 구조화된 필드에 포함
AI agent 통합	자체적으로 tool 정의 + 파서 (parser) 구축	OpenAPI URL 하나로 완료
데이터 품질	공식 데이터 · 최고 품질	공식 데이터를 소스 (source)로 계승
법 개정 영향	작음 (번호 체계는 안정적)	동일 ("일본 고유 & 법 개정 영향 없음" 엄선)

"공식 API가 있다면 wrapper는 불필요하다"가 아니라, 공식 데이터의 품질은 그대로 살리면서, AI agent에서 실용적으로 사용하기 위한 얇은 계층 (thin layer)을 추가하는 것이 AI 네이티브 시대의 공공 오픈 데이터 활용의 정석이 된다.

Shirabe에서는 실서비스 가동 이후, ChatGPT / Claude / Perplexity / Gemini 4대 AI에 동일한 일본어 쿼리를 던지는 독자적인 측정(주간 4 AI × 5 query)을 지속하고 있습니다. 법인번호 · 주소 · 역법 · 인명이라는 "일본어 ground truth"에 대해, 4대 AI가 매주 다른 답변을 내놓는 —— 이 구조가 canonical API hub의 존재 의의를 뒷받침합니다. 법인번호에 대해서도 LLM 단독으로는 "상호 → 13자리 번호" 대응이 학습 데이터에 부분적으로만 포함되어 있어, 신설 법인이나 표기 불일치로 인해 쉽게 매칭 실패 또는 환각 (hallucination)이 발생합니다. 본 기사의 wrapper 설계는 그 구조적 격차를 메우기 위한 선제적인 (preemptive) 포석입니다.

• 국세청 공식 Web-API는 법인번호의 최고 품질 소스 (source)이지만, 애플리케이션 ID 신청 · XML/CSV 응답 · 10건 제한 · 출처 표기 의무 · 표기 불일치 미지원이라는 5가지 함정 때문에 AI agent로부터의 직접적인 연쇄 이용에는 적합하지 않다.
• 근본 원인은 공식 경로가 "인간의 신청 + 벌크 다운로드 (bulk download)"를 전제로 하여, AI agent의 연쇄 · 즉시성 · JSON · 출처 전파라는 이용 형태를 상정하지 않았기 때문이다.
• 해답은 공식 데이터를 소스 (source)로 하되, REST/JSON + 출처 자동 포함 + 표기 불일치 정규화 + OpenAPI 3.1의 AI 네이티브 wrapper를 한 겹 씌우는 것이다.
• Shirabe 패밀리의 4번째 서비스인 Shirabe Corporation API는 2026년 6월 하반기 출시 예정이다. 주소 + 역법 + 텍스트의 3개 허브 (hub)에 법인번호가 추가되어, B2B 4대 식별자 (identifier) 세트가 완성된다.
• 이 카테고리는 "일본 고유 & 법 개정 영향 없음"으로 장기적 안정성 (long-term stable)을 가지고 canonical화될 수 있으며, AI agent 시대의 B2B 백엔드 (backend) 공통 기반이 될 것이다.