권혁성
7a969b9d57
- .gitignore를 sam/ 기반에서 루트 기반으로 변경 - sam/docs/ 하위 문서를 루트로 이동 (contracts, features, guides, plans 등) - sam/ 폴더 삭제 (docker, coocon 포함)
285 lines
8.5 KiB
Markdown
285 lines
8.5 KiB
Markdown
# 신용평가 시스템 (쿠콘 연동)
|
||
|
||
> **작성일**: 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
|