API 시작 가이드

curl -X GET \
  "https://api.bizscan.kr/biz/1234567890/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "bizno": "1234567890",
  "biz_name": "비즈스캔",
  "ceo": "홍길동",
  "ceo_source": "ftc_online",
  "status": "정상영업",
  "licenses": { "total": 3, "active": 2 },
  "sanctions": { "total": 0 },
  "hygiene": { "available": true, "latest": { "grade": "우수" } }
}

Authorization: Bearer bscan_xxxxx

x-api-key: bscan_xxxxx

• API 키를 절대 클라이언트(프론트엔드, 모바일 앱)에 노출하지 마세요.
• 반드시 서버 사이드(백엔드)에서 호출하세요.
• 키가 노출된 경우 대시보드에서 즉시 키를 재발급받으세요.
• 환경변수로 관리하고, 코드에 직접 하드코딩하지 마세요.

curl "https://api.bizscan.kr/health"

{ "status": "ok" }

curl -X POST "https://api.bizscan.kr/biz/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businesses": [
      {
        "b_no": "1234567890",
        "start_dt": "20200101",
        "p_nm": "홍길동"
      }
    ]
  }'

{
  "b_stt": "계속사업자",
  "b_stt_cd": "01",
  "tax_type": "일반과세자",
  "tax_type_cd": "01",
  "end_dt": null,
  "utcc_yn": "N",
  "tax_type_change_dt": null,
  "invoice_apply_dt": "2020-01-15",
  "rbf_tax_type": "해당없음",
  "rbf_tax_type_cd": null
}

// 400 Bad Request
{ "error": "사업자번호 10자리를 정확히 입력해주세요." }

// 401 Unauthorized
{ "error": "Unauthorized" }

curl "https://api.bizscan.kr/biz/1234567890/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "bizno": "1234567890",
  "biz_name": "비즈스캔",
  "ceo": "홍길동",
  "ceo_source": "ftc_online",
  "address": "서울특별시 강남구 테헤란로 123",
  "phone": "02-1234-5678",
  "category": "소프트웨어 개발업",
  "status": "정상영업",
  "registered_at": "20200101",
  "platform": null,
  "nts": {
    "b_stt": "계속사업자",
    "b_stt_cd": "01",
    "tax_type": "일반과세자",
    "tax_type_cd": "01",
    "end_dt": null,
    "utcc_yn": "N"
  },
  "licenses": { "total": 3, "active": 2 },
  "sanctions": { "total": 0 },
  "hygiene": {
    "available": true,
    "latest": {
      "grade": "우수",
      "valid_to": "2027-03-15",
      "biz_name": "비즈스캔"
    }
  }
}

// 404 Not Found
{ "error": "Not Found", "message": "사업자번호를 찾을 수 없습니다" }

curl "https://api.bizscan.kr/biz/1234567890/license?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "total": 3,
  "page": 1,
  "limit": 20,
  "data": [
    {
      "mgt_no": "2020-서울-강남-00001",
      "biz_name": "비즈스캔",
      "license_type": "일반음식점",
      "status": "영업중",
      "issued_at": "2020-01-15",
      "address": "서울 강남구 테헤란로 123",
      "phone": "02-1234-5678"
    },
    {
      "mgt_no": "2021-서울-강남-00042",
      "biz_name": "비즈스캔 2호점",
      "license_type": "휴게음식점",
      "status": "폐업",
      "issued_at": "2021-06-01",
      "address": "서울 강남구 역삼로 45",
      "phone": null
    },
    {
      "mgt_no": "2022-서울-강남-00103",
      "biz_name": "비즈스캔 베이커리",
      "license_type": "제과점",
      "status": "영업중",
      "issued_at": "2022-03-10",
      "address": "서울 강남구 논현로 78",
      "phone": "02-5678-1234"
    }
  ]
}

curl "https://api.bizscan.kr/biz/1234567890/sanctions" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "sanctions": {
    "total": 1,
    "data": [
      {
        "sanction_date": "2023-06-15",
        "sanction_type": "영업정지",
        "violation": "식품위생법 위반",
        "content": "영업정지 10일"
      }
    ]
  },
  "hygiene": {
    "available": true,
    "latest": {
      "grade": "우수",
      "valid_to": "2027-03-15",
      "biz_name": "비즈스캔"
    },
    "history": [
      {
        "grade": "우수",
        "issued_at": "2024-03-15",
        "valid_to": "2027-03-15"
      },
      {
        "grade": "좋음",
        "issued_at": "2021-03-20",
        "valid_to": "2024-03-20"
      }
    ]
  }
}

curl "https://api.bizscan.kr/biz/1234567890/report" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "bizno": "1234567890",
  "biz_name": "비즈스캔",
  "ceo": "홍길동",
  "ceo_source": "ftc_online",
  "address": "서울특별시 강남구 테헤란로 123",
  "phone": "02-1234-5678",
  "category": "소프트웨어 개발업",
  "status": "정상영업",
  "registered_at": "20200101",
  "platform": "스마트스토어",
  "nts": {
    "b_stt": "계속사업자",
    "b_stt_cd": "01",
    "tax_type": "일반과세자",
    "tax_type_cd": "01",
    "end_dt": null,
    "utcc_yn": "N",
    "tax_type_change_dt": null,
    "invoice_apply_dt": "2020-01-15",
    "rbf_tax_type": "해당없음",
    "rbf_tax_type_cd": null
  },
  "licenses": {
    "total": 3,
    "active": 2,
    "data": [
      {
        "biz_name": "비즈스캔",
        "license_type": "일반음식점",
        "status": "영업중",
        "issued_at": "2020-01-15",
        "address": "서울 강남구 테헤란로 123",
        "phone": "02-1234-5678"
      },
      {
        "biz_name": "비즈스캔 2호점",
        "license_type": "휴게음식점",
        "status": "폐업",
        "issued_at": "2021-06-01",
        "address": "서울 강남구 역삼로 45",
        "phone": null
      }
    ]
  },
  "sanctions": {
    "total": 1,
    "data": [
      {
        "sanction_type": "영업정지",
        "sanction_date": "2023-06-15",
        "violation": "식품위생법 위반",
        "content": "영업정지 10일"
      }
    ]
  },
  "hygiene": {
    "available": true,
    "latest": {
      "grade": "우수",
      "valid_to": "2027-03-15",
      "biz_name": "비즈스캔"
    }
  },
  "ceo_sources": [
    {
      "ceo": "홍길동",
      "source": "ftc_online",
      "biz_name": "비즈스캔",
      "status": "정상영업",
      "registered_at": "2020-01-15",
      "platform": "스마트스토어",
      "category": "소프트웨어 개발업",
      "address": "서울 강남구 테헤란로 123"
    },
    {
      "ceo": "홍길동",
      "source": "fsc_corp",
      "biz_name": "비즈스캔",
      "status": null,
      "registered_at": null,
      "platform": null,
      "category": null,
      "address": "서울 강남구"
    }
  ],
  "response_ms": 142
}

const API_KEY = process.env.BIZSCAN_API_KEY;
const BIZNO = "1234567890";

// 통합 리포트 조회
const res = await fetch(
  `https://api.bizscan.kr/biz/${BIZNO}/report`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${res.status}: ${err.error}`);
}

const data = await res.json();
console.log(`대표자: ${data.ceo}`);
console.log(`인허가: ${data.licenses.total}건 (활성 ${data.licenses.active}건)`);
console.log(`행정처분: ${data.sanctions.total}건`);

import os
import requests

API_KEY = os.environ["BIZSCAN_API_KEY"]
BIZNO = "1234567890"

# 통합 리포트 조회
res = requests.get(
    f"https://api.bizscan.kr/biz/{BIZNO}/report",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
res.raise_for_status()

data = res.json()
print(f"대표자: {data['ceo']}")
print(f"인허가: {data['licenses']['total']}건")
print(f"행정처분: {data['sanctions']['total']}건")

import requests

res = requests.post(
    "https://api.bizscan.kr/biz/verify",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "businesses": [{
            "b_no": "1234567890",
            "start_dt": "20200101",
            "p_nm": "홍길동"
        }]
    }
)
data = res.json()
print(f"상태: {data['b_stt']} / 과세유형: {data['tax_type']}")

curl -s \
  "https://api.bizscan.kr/biz/1234567890/report" \
  -H "Authorization: Bearer bscan_xxxxx" | jq .

curl -s \
  "https://api.bizscan.kr/biz/1234567890/license?page=2&limit=10" \
  -H "x-api-key: bscan_xxxxx" | jq .

{
  "error": "에러 유형",
  "message": "상세 설명 (선택)"
}

// 400 — 잘못된 사업자번호
{ "error": "사업자번호 10자리를 정확히 입력해주세요." }

// 401 — 인증 실패
{ "error": "Unauthorized" }

// 403 — 플랜 부족
{ "error": "Forbidden", "message": "Basic 이상 플랜이 필요합니다" }

// 404 — 데이터 없음
{ "error": "Not Found", "message": "사업자번호를 찾을 수 없습니다" }

// 429 — 한도 초과
{ "error": "Too Many Requests", "message": "월간 조회 한도를 초과했습니다" }