From 896c84475c90e53331a9270315538002581551e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 2 Mar 2026 18:39:46 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20[credit]=20=EC=8B=A0=EC=9A=A9=ED=8F=89?= =?UTF-8?q?=EA=B0=80=20=EA=B0=9C=EB=B0=9C=EB=AC=B8=EC=84=9C=20=ED=8E=98?= =?UTF-8?q?=EC=9D=B4=EC=A7=80=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 쿠콘(KooCon) API 연동 가이드 10개 섹션 구성 - 라우트, 컨트롤러, Blade 뷰 추가 --- .../Controllers/Credit/CreditController.php | 12 + resources/views/credit/dev-guide.blade.php | 601 ++++++++++++++++++ routes/web.php | 3 + 3 files changed, 616 insertions(+) create mode 100644 resources/views/credit/dev-guide.blade.php diff --git a/app/Http/Controllers/Credit/CreditController.php b/app/Http/Controllers/Credit/CreditController.php index f3081acc..3d7142a5 100644 --- a/app/Http/Controllers/Credit/CreditController.php +++ b/app/Http/Controllers/Credit/CreditController.php @@ -17,6 +17,18 @@ */ class CreditController extends Controller { + /** + * 신용평가 개발문서 페이지 + */ + public function devGuide(Request $request): View|Response + { + if ($request->header('HX-Request')) { + return response('', 200)->header('HX-Redirect', route('credit.dev-guide.index')); + } + + return view('credit.dev-guide'); + } + /** * 신용평가 조회 이력 목록 */ diff --git a/resources/views/credit/dev-guide.blade.php b/resources/views/credit/dev-guide.blade.php new file mode 100644 index 00000000..a864a844 --- /dev/null +++ b/resources/views/credit/dev-guide.blade.php @@ -0,0 +1,601 @@ +@extends('layouts.app') + +@section('title', '신용평가 개발문서') + +@section('content') +
+ + {{-- 페이지 헤더 --}} +
+
+ 신용평가 + + + + 개발문서 +
+

신용평가 연동 개발문서

+

쿠콘(KooCon/나이스평가정보) API를 통한 기업 신용정보 조회 시스템 가이드

+
+ + {{-- 목차 --}} +
+

📋 목차

+ +
+ + {{-- 본문 --}} +
+ + {{-- 섹션 1: 쿠콘이란? --}} +
+
+
+
1
+

쿠콘(KooCon)이란?

+
+ +
+

쿠콘(KooCon)은 나이스평가정보가 운영하는 금융 데이터 API 플랫폼입니다. 기업의 신용정보, 재무정보, 연체정보 등을 API로 조회할 수 있습니다.

+ +
+

파트너 구조

+
+
+

쿠콘 (나이스평가정보)

+

API 플랫폼

+
+ → +
+

(주)코드브릿지엑스

+

파트너사 (API 키 보유)

+
+ → +
+

각 테넌트

+

SAM을 통해 조회

+
+
+
+ +
+

SAM에서 쿠콘을 쓰는 이유

+
    +
  • • 거래처/협력업체의 신용 안전성을 사전에 파악
    • +
  • • 단기연체, 당좌거래정지, 법정관리 등 위험 신호를 한눈에 확인
    • +
  • • 국세청 사업자등록 상태(영업/휴업/폐업)를 동시에 조회
    • +
  • • 모든 조회 결과를 DB에 기록하여 이력 관리 및 감사 추적
    • +
+
+
+
+
+ + {{-- 섹션 2: 시스템 구조 --}} +
+
+
+
2
+

시스템 구조

+
+ +
+ 
+┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
+│  SAM 관리자    │────▶│  CreditController    │────▶│  CooconService   │
+│  신용조회 요청  │     │  search()            │     │  7개 API 순차 호출 │
+└──────────────┘     └─────────┬───────────┘     └────────┬─────────┘
+                               │                          │
+                               │                          ▼
+                               │                 ┌──────────────────┐
+                               │                 │  쿠콘 서버         │
+                               │                 │  (나이스평가정보)    │
+                               │                 └──────────────────┘
+                               │
+                               ├────▶ NtsBusinessService
+                               │        └──▶ 국세청 공공데이터포털
+                               │
+                               └────▶ CreditInquiry::create()
+                                        └──▶ DB 저장 (이력 기록)
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + +
프로젝트프로토콜대상용도
MNGREST/JSON쿠콘 API기업 신용정보 7개 항목 조회
MNGREST/JSON국세청 API사업자등록 상태(영업/휴업/폐업) 확인
+
+
+
+ + {{-- 섹션 3: 조회 가능한 신용정보 --}} +
+
+
+
3
+

조회 가능한 신용정보

+
+ +

사업자번호 1개를 입력하면 아래 7개 API를 순차 호출하여 한 번에 결과를 수집합니다.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
API ID조회 항목데이터 출처비개발자 설명
OA08기업 기본정보나이스평가정보회사명, 대표자, 주소, 업종, 설립일
OA12신용요약정보나이스평가정보각종 이슈 건수를 한눈에 요약한 데이터
OA13단기연체정보한국신용정보원대출금, 카드 등 단기 연체 발생 여부
OA14신용도판단정보 (KCI)한국신용정보원 + 공공정보부도, 세금체납, 가압류 등 공적 기록
OA15신용도판단정보 (CB)신용정보사민간 신용정보사가 수집한 부정적 정보
OA16당좌거래정지정보금융결제원수표 부도로 인한 은행 거래 정지 여부
OA17법정관리/워크아웃법원회생절차/파산 진행 여부
+
+ +
+ 이슈 판단 기준: OA13~OA17 중 1건이라도 건수가 있으면 "이슈 있음"으로 표시됩니다. 이슈가 있는 업체와의 거래 시 주의가 필요합니다. +
+
+
+ + {{-- 섹션 4: 국세청 사업자 조회 --}} +
+
+
+
4
+

국세청 사업자등록 조회

+
+ +
+

신용정보와 별도로, 국세청 공공데이터포털 API를 통해 사업자등록 상태를 동시에 확인합니다.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
상태코드상태의미
01계속사업자정상 영업 중
02휴업자영업 일시 중지
03폐업자사업 종료 (폐업일 포함)
+
+ +
+ API 출처: 공공데이터포털 (api.odcloud.kr) — 사업자등록정보 진위확인 및 상태조회 서비스 +
+
+
+
+ + {{-- 섹션 5: 신용조회 실행 흐름 --}} +
+
+
+
5
+

신용조회 실행 흐름

+
+ +
+ {{-- 단계별 흐름 --}} +
+
+ 1 +
+

사업자번호 입력

+

SAM 신용평가 조회 페이지에서 사업자번호(10자리) 또는 법인번호(13자리) 입력

+
+
+
+ 2 +
+

쿠콘 API 7개 순차 호출 (OA08 ~ OA17)

+

기업정보, 신용요약, 연체, KCI, CB, 당좌정지, 법정관리 — 일부 실패해도 나머지는 저장 (status='partial')

+
+
+
+ 3 +
+

국세청 API 동시 호출

+

사업자등록 상태(영업/휴업/폐업) 확인 — 쿠콘과 별도 API

+
+
+
+ 4 +
+

DB 저장 및 결과 표시

+

모든 원본 응답을 JSON으로 저장, 이슈 건수 요약 표시, 조회 이력에 기록

+
+
+
+ +
+ 참고: 1회 조회 시 쿠콘 API 7개 + 국세청 API 1개 = 총 8개 API를 호출합니다. 타임아웃은 API당 30초이며, 전체 소요시간은 보통 3~10초입니다. +
+
+
+
+ + {{-- 섹션 6: 과금 정책 --}} +
+
+
+
6
+

과금 정책

+
+ +
+
+
+

5건

+

월 무료 할당량

+
+
+

2,000원

+

초과 건당 요금

+
+
+

max(0, N-5) × 2,000

+

계산 공식

+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
월 조회 건수무료유료요금
3건300원
5건500원
10건5510,000원
20건51530,000원
+
+ +
+ 집계 확인: SAM → 신용평가 → 조회회수 집계에서 테넌트별/월별 사용량과 요금을 확인할 수 있습니다. 본사(tenant_id=1)는 전체 테넌트 현황을 조회합니다. +
+
+
+
+ + {{-- 섹션 7: 환경 설정 --}} +
+
+
+
7
+

환경 설정 (테스트/운영)

+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + +
환경API URL과금용도
테스트dev2.coocon.co.kr:8443무료개발/검증
운영sgw.coocon.co.kr유료실 서비스
+
+ +
+

설정 관리 방법

+
    +
  1. SAM MNG → 신용평가 → 설정 관리
    2. +
  2. 환경(테스트/운영)별로 API 키와 URL 설정
    3. +
  3. 활성화 토글로 사용할 설정 선택 (환경당 1개만 활성화 가능)
    4. +
  4. "연결 테스트" 버튼으로 API 정상 연결 확인
    5. +
+
+ +
+ ⚠️ 주의: 운영 환경 설정으로 전환하면 실제 과금이 발생합니다. 개발/테스트 중에는 반드시 테스트 환경을 사용하세요. +
+
+
+
+ + {{-- 섹션 8: 주요 테이블 --}} +
+
+
+
8
+

주요 테이블

+
+ +
+ + + + + + + + + + + + + + + + + + + + +
테이블모델역할
coocon_configsCooconConfig쿠콘 API 설정 (키, URL, 환경, 활성화)
credit_inquiriesCreditInquiry조회 이력 (기업정보, 이슈건수, 원본 JSON, 국세청 상태)
+
+ +
+

credit_inquiries 주요 컬럼

+
+ inquiry_key — 조회 고유키 (32자) + raw_summary — OA12 원본 JSON + company_key — 사업자/법인번호 + raw_short_term_overdue — OA13 원본 + nts_status_code — 국세청 상태 + raw_negative_info_kci — OA14 원본 + short_term_overdue_cnt — 연체 건수 + raw_negative_info_cb — OA15 원본 + suspension_info_cnt — 당좌정지 건수 + status — success/partial/failed +
+
+
+
+ + {{-- 섹션 9: 에러 코드 --}} +
+
+
+
9
+

에러 코드

+
+ +
+
+

쿠콘 API

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
코드설명대응
NO_CONFIGAPI 설정 없음설정 관리에서 활성화된 설정 확인
HTTP_ERRORHTTP 통신 오류쿠콘 서버 상태 확인, 네트워크 확인
00000000정상 처리—
(기타)쿠콘 API 에러RSLT_MSG 에러 메시지 참조
+
+
+ +
+

국세청 API

+
+ + + + + + + + + + + + + + + + + +
코드설명
INVALID_FORMAT사업자번호 형식 오류 (10자리 숫자)
NOT_FOUND등록되지 않은 사업자번호
+
+
+
+
+
+ + {{-- 섹션 10: 관련 파일 경로 --}} +
+
+
+
10
+

관련 파일 경로

+
+ +
+
+

MNG 프로젝트

+
+

컨트롤러 app/Http/Controllers/Credit/CreditController.php

+

컨트롤러 app/Http/Controllers/Credit/CreditUsageController.php

+

서비스 app/Services/Coocon/CooconService.php ← 쿠콘 API 클라이언트

+

서비스 app/Services/Nts/NtsBusinessService.php ← 국세청 API

+

모델 app/Models/Coocon/CooconConfig.php

+

모델 app/Models/Credit/CreditInquiry.php

+

뷰 resources/views/credit/**/*.blade.php

+
+
+ +
+

문서

+
+

가이드 docs/features/credit-evaluation/README.md

+
+
+
+
+
+ +
+ + {{-- 하단 바로가기 --}} +
+

바로 이동하기

+
+ 신용평가 조회 + 조회회수 집계 + 설정 관리 +
+
+ +
+@endsection diff --git a/routes/web.php b/routes/web.php index f496748e..9a61947e 100644 --- a/routes/web.php +++ b/routes/web.php @@ -690,6 +690,9 @@ |-------------------------------------------------------------------------- */ Route::prefix('credit')->name('credit.')->group(function () { + // 신용평가 개발문서 + Route::get('/dev-guide', [\App\Http\Controllers\Credit\CreditController::class, 'devGuide'])->name('dev-guide.index'); + // 조회 이력 목록 Route::get('/inquiry', [\App\Http\Controllers\Credit\CreditController::class, 'inquiry'])->name('inquiry.index'); Route::post('/inquiry/search', [\App\Http\Controllers\Credit\CreditController::class, 'search'])->name('inquiry.search');