BizAddr API 문서

사업자 상태 조회·대량검증·감시 목록을 코드에서 직접 호출할 수 있습니다. API는 Business 요금제부터 사용할 수 있습니다.

인증

모든 요청에 X-API-Key 헤더로 API 키를 전달합니다. 키는 콘솔의 API 키 화면에서 발급받습니다 — 발급 즉시 한 번만 표시되니 안전한 곳에 보관하세요.

curl -H "X-API-Key: 발급받은키" https://api.bizaddr.com/me

단건 조회

사업자등록번호로 국세청 등록상태를 확인합니다. 상호·주소를 함께 보내면 반송 위험까지 진단합니다.

curl -X POST https://api.bizaddr.com/verify \
  -H "X-API-Key: 발급받은키" \
  -H "Content-Type: application/json" \
  -d '{
    "b_no": "1234567890",
    "name": "예시상사",
    "address": "서울특별시 강남구 테헤란로 1"
  }'

응답 예시

{
  "biz_status": "계속사업자",
  "bounce_prob": 0.08,
  "grade": "A",
  "action": "SEND",
  "fixed_zipcode": "06234",
  "fixed_address": "서울특별시 강남구 테헤란로 1",
  "reasons": ["[안전 -0.60] 국세청: 계속사업자 (nts)", "..."]
}

대량 검증

CSV·엑셀·JSON 파일(multipart/form-data)을 올리면 행마다 검증합니다. 비동기로 처리되며, job_id로 진행률과 결과를 조회합니다.

curl -X POST "https://api.bizaddr.com/batch?offline=false&paid=false" \
  -H "X-API-Key: 발급받은키" \
  -F "file=@거래처명단.xlsx"

{ "job_id": "a1b2c3d4e5f6", "total": 320 }

진행 상태와 상위 결과를 조회합니다. status가 "done"이 될 때까지 폴링하세요(1초 간격 권장).

curl https://api.bizaddr.com/batch/a1b2c3d4e5f6?preview=100 \
  -H "X-API-Key: 발급받은키"

실제 반송 결과를 기록합니다. 쌓일수록 판정 정확도가 실측 데이터로 개선됩니다.

curl -X POST https://api.bizaddr.com/batch/a1b2c3d4e5f6/label \
  -H "X-API-Key: 발급받은키" -H "Content-Type: application/json" \
  -d '{"row_id": 3, "bounced": true, "reason": "수취인불명"}'

감시 목록

거래처를 감시 목록에 등록합니다. 요금제별 주기로 자동 재확인하고, 폐업이 감지되면 알림을 보냅니다.

curl -X POST https://api.bizaddr.com/watch \
  -H "X-API-Key: 발급받은키" -H "Content-Type: application/json" \
  -d '{"biz_no": "1234567890", "name": "예시상사", "address": "..."}'

감시 목록 전체를 조회합니다.

감시를 해제합니다.

거래처 하나의 등급 변화 이력을 시간순으로 조회합니다. Business 요금제 전용입니다.

요청 한도·오류

요금제별 월간 조회 건수 한도가 있습니다. 초과 시 429를 반환합니다. 한도는 GET /me로 확인할 수 있습니다.

API 관련 문의는 [email protected]으로 보내주세요.