Files

김보곤 52417acad6 docs: [credit] 신용평가 시스템 내부 문서 추가

- 쿠콘 API 연동, 국세청 API, DB 구조, 과금 정책 등 정리

2026-03-02 18:40:30 +09:00

README.md

docs: [credit] 신용평가 시스템 내부 문서 추가

2026-03-02 18:40:30 +09:00

README.md

신용평가 시스템 (쿠콘 연동)

작성일: 2026-03-02 상태: 운영중

1. 개요

1.1 목적

SAM에서 거래처/협력업체의 기업 신용정보를 조회하여, 거래 안전성을 사전 판단하는 시스템이다.

1.2 핵심 원칙

쿠콘(KooCon/나이스평가정보) API로 기업 신용정보 7개 항목 조회
국세청 공공데이터포털 API로 사업자등록 상태(영업/휴업/폐업) 확인
모든 조회 결과는 DB에 원본 저장 (감사 추적용)
테넌트별 월 5건 무료, 초과 시 건당 2,000원 과금

2. 시스템 구조

2.1 전체 흐름

사용자 (SAM MNG)
    │
    ▼
CreditController::search()
    │
    ├──▶ CooconService::getAllCreditInfo()
    │       ├── OA08: 기업 기본정보
    │       ├── OA12: 신용요약정보
    │       ├── OA13: 단기연체정보
    │       ├── OA14: 신용도판단정보 (KCI)
    │       ├── OA15: 신용도판단정보 (CB)
    │       ├── OA16: 당좌거래정지정보
    │       └── OA17: 법정관리/워크아웃
    │
    ├──▶ NtsBusinessService::getBusinessStatus()
    │       └── 국세청 사업자등록 상태 조회
    │
    └──▶ CreditInquiry::createFromApiResponse()
            └── DB에 조회 이력 저장

2.2 파트너 구조

역할	대상	설명
API 제공사	쿠콘(KooCon) / 나이스평가정보	기업 신용정보 API 플랫폼
파트너사	(주)코드브릿지엑스	API 키 보유, 쿠콘과 직접 계약
이용사	각 테넌트 (주일, 경동 등)	SAM을 통해 신용조회 실행

3. 쿠콘(KooCon) API

3.1 API 엔드포인트

환경	URL
테스트	`https://dev2.coocon.co.kr:8443/sol/gateway/oapi_relay.jsp`
운영	`https://sgw.coocon.co.kr/sol/gateway/oapi_relay.jsp`

3.2 인증 방식

API_KEY: 쿠콘에서 발급받은 인증키 (DB coocon_configs 테이블에서 관리)
API_ID: 조회할 API 식별자 (OA08~OA17)
TR_SEQ: 거래일련번호 (중복 방지용, YmdHis + 마이크로초 6자리)

3.3 요청 형식

{
    "API_KEY": "발급받은_API_키",
    "API_ID": "OA12",
    "TR_SEQ": "20260302173000123456",
    "COMPANY_KEY": "1234567890"
}

Method: POST
Content-Type: application/json
Timeout: 30초

3.4 API 목록

API ID	상수명	설명	데이터 출처
`OA08`	`API_COMPANY_INFO`	기업 기본정보	나이스평가정보
`OA12`	`API_CREDIT_SUMMARY`	신용요약정보 (이슈 건수 요약)	나이스평가정보
`OA13`	`API_SHORT_TERM_OVERDUE`	단기연체정보	한국신용정보원
`OA14`	`API_NEGATIVE_INFO_KCI`	신용도판단정보 (KCI)	한국신용정보원 + 공공정보
`OA15`	`API_NEGATIVE_INFO_CB`	신용도판단정보 (CB)	신용정보사
`OA16`	`API_SUSPENSION_INFO`	당좌거래정지정보	금융결제원
`OA17`	`API_WORKOUT_INFO`	법정관리/워크아웃정보	법원

3.5 응답 형식

{
    "RSLT_CD": "00000000",
    "RSLT_MSG": "정상처리되었습니다.",
    "RSLT_DATA": { ... }
}

RSLT_CD === '00000000': 성공
기타 값: 에러 (에러 메시지는 RSLT_MSG에 포함)

4. 국세청 사업자등록 조회 API

4.1 API 정보

항목	값
URL	`https://api.odcloud.kr/api/nts-businessman/v1/status`
인증	serviceKey (쿼리 파라미터)
출처	공공데이터포털

4.2 상태 코드

코드	상태	설명
`01`	계속사업자	정상 영업 중
`02`	휴업자	영업 중지
`03`	폐업자	사업 종료

5. 데이터베이스

5.1 `coocon_configs` — API 설정

컬럼	타입	설명
`id`	BIGINT PK
`name`	VARCHAR(100)	설정 이름
`environment`	ENUM('test', 'production')	환경
`api_key`	VARCHAR(100)	쿠콘 API 키
`base_url`	VARCHAR(255)	API 기본 URL
`description`	TEXT	설명
`is_active`	BOOLEAN	활성화 여부

규칙: 환경당 1개만 활성화 가능. 새 설정 활성화 시 기존 설정은 자동 비활성화.

5.2 `credit_inquiries` — 조회 이력

컬럼	타입	설명
`id`	BIGINT PK
`tenant_id`	BIGINT FK	테넌트
`inquiry_key`	VARCHAR(32) UNIQUE	조회 고유키
`company_key`	VARCHAR(20)	사업자번호/법인번호
`company_name`	VARCHAR	업체명
`user_id`	BIGINT FK	조회자
`inquired_at`	TIMESTAMP	조회 일시
`nts_status`	VARCHAR(20)	국세청 상태
`nts_status_code`	VARCHAR(2)	국세청 상태코드
`short_term_overdue_cnt`	UINT	단기연체 건수
`negative_info_kci_cnt`	UINT	KCI 건수
`negative_info_pb_cnt`	UINT	공공정보 건수
`negative_info_cb_cnt`	UINT	CB 건수
`suspension_info_cnt`	UINT	당좌거래정지 건수
`workout_cnt`	UINT	법정관리/워크아웃 건수
`raw_*`	JSON	각 API 원본 응답 (7개 + NTS)
`status`	ENUM	success / partial / failed

6. 과금 정책

항목	값
월 무료 할당량	5건
초과 건당 요금	2,000원
계산식	`max(0, (조회건수 - 5)) × 2,000`

요금 예시

월 조회 건수	무료	유료	요금
3건	3	0	0원
5건	5	0	0원
10건	5	5	10,000원
20건	5	15	30,000원

7. 환경 설정

7.1 테스트/운영 분리

환경	API URL	설명
테스트	`dev2.coocon.co.kr:8443`	개발/검증용 (과금 없음)
운영	`sgw.coocon.co.kr`	실 서비스 (과금 발생)

coocon_configs 테이블에서 환경별로 별도 설정 관리
각 환경에서 is_active=true인 설정 1개만 사용

7.2 필요한 설정

항목	관리 위치	설명
쿠콘 API 키	DB (`coocon_configs`)	쿠콘에서 발급
쿠콘 API URL	DB (`coocon_configs`)	환경별 URL
국세청 API 키	코드 내 하드코딩	공공데이터포털 발급

8. MNG 라우트

Method	Path	설명
GET	`/credit/inquiry`	조회 이력 목록
POST	`/credit/inquiry/search`	신용정보 조회 실행
POST	`/credit/inquiry/test`	API 연결 테스트
GET	`/credit/inquiry/{key}/raw`	원본 데이터 조회
GET	`/credit/inquiry/{key}/report`	리포트 조회
DELETE	`/credit/inquiry/{id}`	이력 삭제
GET	`/credit/usage`	조회회수 집계
GET	`/credit/settings`	설정 관리
POST	`/credit/settings`	설정 생성
PUT	`/credit/settings/{id}`	설정 수정
DELETE	`/credit/settings/{id}`	설정 삭제
POST	`/credit/settings/{id}/toggle`	활성화 토글

9. 에러 코드

9.1 쿠콘 API

코드	설명
`NO_CONFIG`	API 설정 없음
`HTTP_ERROR`	HTTP 통신 오류
`EXCEPTION`	예외 발생
`RSLT_CD ≠ 00000000`	쿠콘 API 에러 (RSLT_MSG 참조)

9.2 국세청 API

코드	설명
`INVALID_FORMAT`	사업자번호 형식 오류
`NOT_FOUND`	조회 결과 없음
`HTTP_ERROR`	HTTP 통신 오류

10. 관련 파일

MNG 프로젝트

구분	경로
컨트롤러	`app/Http/Controllers/Credit/CreditController.php`
컨트롤러	`app/Http/Controllers/Credit/CreditUsageController.php`
서비스	`app/Services/Coocon/CooconService.php`
서비스	`app/Services/Nts/NtsBusinessService.php`
모델	`app/Models/Coocon/CooconConfig.php`
모델	`app/Models/Credit/CreditInquiry.php`
뷰	`resources/views/credit/inquiry/index.blade.php`
뷰	`resources/views/credit/usage/index.blade.php`
뷰	`resources/views/credit/settings/index.blade.php`

API 프로젝트 (마이그레이션)

경로
`database/migrations/2026_01_22_192637_create_coocon_configs_table.php`
`database/migrations/2026_01_22_201143_create_credit_inquiries_table.php`
`database/migrations/2026_01_22_203001_add_company_info_to_credit_inquiries_table.php`
`database/migrations/2026_01_28_163000_add_tenant_id_to_credit_inquiries_table.php`

최종 업데이트: 2026-03-02

README.md Unescape Escape

신용평가 시스템 (쿠콘 연동)

1. 개요

1.1 목적

1.2 핵심 원칙

2. 시스템 구조

2.1 전체 흐름

2.2 파트너 구조

3. 쿠콘(KooCon) API

3.1 API 엔드포인트

3.2 인증 방식

3.3 요청 형식

3.4 API 목록

3.5 응답 형식

4. 국세청 사업자등록 조회 API

4.1 API 정보

4.2 상태 코드

5. 데이터베이스

5.1 coocon_configs — API 설정

5.2 credit_inquiries — 조회 이력

6. 과금 정책

요금 예시

7. 환경 설정

7.1 테스트/운영 분리

7.2 필요한 설정

8. MNG 라우트

9. 에러 코드

9.1 쿠콘 API

9.2 국세청 API

10. 관련 파일

MNG 프로젝트

API 프로젝트 (마이그레이션)

README.md

5.1 `coocon_configs` — API 설정

5.2 `credit_inquiries` — 조회 이력