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

> **작성일**: 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 요청 형식

```json
{
    "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 응답 형식

```json
{
    "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