docs:바로빌 카카오톡 연동 개발문서 초안 작성

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-14 15:09:45 +09:00
parent aab9dc0799
commit 579965ed5c
2 changed files with 253 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -122,6 +122,7 @@ docs/

 | 문서 | 설명 |
 |------|------|
+| [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 (알림톡/친구톡) 연동 |
 | [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 |
 | [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 |
 | [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) |
--- a/features/barobill-kakaotalk/README.md
+++ b/features/barobill-kakaotalk/README.md
@@ -0,0 +1,252 @@
+# 바로빌 카카오톡 (알림톡/친구톡) 연동
+
+> **문서 버전**: 0.1 (초안)
+> **작성일**: 2026-02-14
+> **최종 수정**: 2026-02-14
+> **상태**: 개발 중 (사전 준비 단계)
+> **대상 프로젝트**: MNG
+
+---
+
+## 1. 개요
+
+### 1.1 목적
+
+바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여,
+고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다.
+
+### 1.2 사전 요구사항 (미완료)
+
+| 항목 | 상태 | 설명 |
+|------|------|------|
+| 법인 명의 휴대폰 준비 | **대기** | 카카오톡 채널 가입에 법인 명의 번호 필요 |
+| 카카오톡 채널 개설 | **대기** | [카카오비즈니스](https://business.kakao.com) 에서 채널 생성 |
+| 바로빌 카카오톡 서비스 신청 | **대기** | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
+| 채널 연동 (바로빌↔카카오) | **대기** | 바로빌 관리 URL에서 채널 연동 처리 |
+| 알림톡 템플릿 등록/검수 | **대기** | 카카오 검수 승인 필요 (1~3 영업일) |
+
+### 1.3 알림톡 vs 친구톡
+
+| 구분 | 알림톡 | 친구톡 |
+|------|--------|--------|
+| **용도** | 정보성 메시지 (주문확인, 배송안내 등) | 광고성 메시지 (프로모션, 이벤트 등) |
+| **수신 대상** | 모든 카카오톡 사용자 | 채널 친구 추가한 사용자만 |
+| **템플릿** | 필수 (카카오 사전 검수) | 불필요 (자유 형식) |
+| **광고 표시** | 불가 | 필수 (`(광고)` 표기) |
+| **이미지 첨부** | 불가 | 가능 (이미지/와이드 이미지) |
+| **비용** | 건당 약 8~9원 | 건당 약 15~20원 |
+| **SMS 대체발송** | 설정 가능 | 설정 가능 |
+
+---
+
+## 2. 아키텍처
+
+### 2.1 시스템 구조
+
+```
+SAM MNG (브라우저)
+    │
+    ├─ [페이지] /barobill/kakaotalk/*          ← Blade 뷰
+    │      KakaotalkController (페이지 렌더링)
+    │
+    └─ [API]  /api/admin/barobill/kakaotalk/*   ← AJAX 호출
+           BarobillKakaotalkController
+                │
+                └─ BarobillService (SOAP 클라이언트)
+                       │
+                       └─ 바로빌 KAKAOTALK.asmx (WSDL)
+                              │
+                              └─ 카카오톡 서버
+```
+
+### 2.2 바로빌 SOAP API 엔드포인트
+
+| 환경 | WSDL URL |
+|------|----------|
+| **테스트** | `https://testws.baroservice.com/KAKAOTALK.asmx?WSDL` |
+| **운영** | `https://ws.baroservice.com/KAKAOTALK.asmx?WSDL` |
+
+---
+
+## 3. 구현 현황
+
+### 3.1 완료된 항목
+
+| 구분 | 파일 | 설명 |
+|------|------|------|
+| SOAP 서비스 | `app/Services/Barobill/BarobillService.php` | kakaotalk SOAP 클라이언트 + 15개 API 메서드 추가 |
+| API 컨트롤러 | `app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php` | 15개 API 엔드포인트 |
+| 페이지 컨트롤러 | `app/Http/Controllers/Barobill/KakaotalkController.php` | 6개 페이지 (index, channels, templates, send, history, guide) |
+| 라우트 (web) | `routes/web.php` | `/barobill/kakaotalk/*` 6개 라우트 |
+| 라우트 (api) | `routes/api.php` | `/api/admin/barobill/kakaotalk/*` 14개 라우트 |
+| 대시보드 뷰 | `views/barobill/kakaotalk/index.blade.php` | 채널 상태 요약, 빠른 메뉴 |
+| 채널 관리 뷰 | `views/barobill/kakaotalk/channels/index.blade.php` | 채널 목록, 관리 URL 연결 |
+| 템플릿 관리 뷰 | `views/barobill/kakaotalk/templates/index.blade.php` | 채널별 템플릿 조회, 상세 모달 |
+| 발송 뷰 | `views/barobill/kakaotalk/send/index.blade.php` | 알림톡/친구톡 탭, 발송 폼 |
+| 전송내역 뷰 | `views/barobill/kakaotalk/history/index.blade.php` | 전송키 조회, 예약 취소 |
+| 사용법 가이드 뷰 | `views/barobill/kakaotalk/guide.blade.php` | 초보자용 8단계 가이드 |
+| 메뉴 등록 | DB (menus 테이블) | 로컬/서버 모두 등록 완료 |
+
+### 3.2 미완료 / 검증 필요 항목
+
+| 항목 | 상태 | 비고 |
+|------|------|------|
+| 채널 API 실제 호출 테스트 | **대기** | 카카오 채널 개설 후 가능 |
+| 템플릿 조회 테스트 | **대기** | 템플릿 등록/검수 후 가능 |
+| 알림톡 발송 테스트 | **대기** | 채널+템플릿 준비 후 가능 |
+| 친구톡 발송 테스트 | **대기** | 채널 친구 추가 후 가능 |
+| SMS 대체발송 테스트 | **대기** | 바로빌 SMS 서비스 활성화 필요 |
+| 대량 발송 테스트 | **대기** | 단건 테스트 완료 후 |
+| 에러 핸들링 고도화 | **대기** | 실제 API 응답 확인 후 개선 |
+
+---
+
+## 4. API 메서드 목록
+
+### 4.1 BarobillService 카카오톡 메서드
+
+| 메서드 | SOAP Action | 설명 |
+|--------|-------------|------|
+| `getKakaotalkChannels` | `GetKakaotalkChannels` | 채널 목록 조회 |
+| `getKakaotalkChannelManagementUrl` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL (바로빌 페이지) |
+| `getKakaotalkTemplates` | `GetKakaotalkTemplates` | 템플릿 목록 조회 |
+| `getKakaotalkTemplateManagementUrl` | `GetKakaotalkTemplateManagementURL` | 템플릿 관리 URL |
+| `sendATKakaotalk` | `SendATKakaotalk` | 알림톡 단건 발송 |
+| `sendATKakaotalkEx` | `SendATKakaotalkEx` | 알림톡 단건 발송 (버튼 포함) |
+| `sendATKakaotalks` | `SendATKakaotalks` | 알림톡 대량 발송 |
+| `sendFTKakaotalk` | `SendFTKakaotalk` | 친구톡 텍스트 단건 |
+| `sendFTKakaotalks` | `SendFTKakaotalks` | 친구톡 텍스트 대량 |
+| `sendFIKakaotalk` | `SendFIKakaotalk` | 친구톡 이미지 |
+| `sendFWKakaotalk` | `SendFWKakaotalk` | 친구톡 와이드 이미지 |
+| `getSendKakaotalk` | `GetSendKakaotalk` | 전송 결과 단건 조회 |
+| `getSendKakaotalks` | `GetSendKakaotalks` | 전송 결과 다건 조회 |
+| `cancelReservedKakaotalk` | `CancelReservedKakaotalk` | 예약 전송 취소 |
+
+### 4.2 REST API 엔드포인트
+
+| Method | URL | 설명 |
+|--------|-----|------|
+| GET | `/api/admin/barobill/kakaotalk/channels` | 채널 목록 |
+| GET | `/api/admin/barobill/kakaotalk/channels/management-url` | 채널 관리 URL |
+| GET | `/api/admin/barobill/kakaotalk/templates` | 템플릿 목록 |
+| GET | `/api/admin/barobill/kakaotalk/templates/management-url` | 템플릿 관리 URL |
+| POST | `/api/admin/barobill/kakaotalk/send/alimtalk` | 알림톡 단건 |
+| POST | `/api/admin/barobill/kakaotalk/send/alimtalk-bulk` | 알림톡 대량 |
+| POST | `/api/admin/barobill/kakaotalk/send/friendtalk` | 친구톡 텍스트 |
+| POST | `/api/admin/barobill/kakaotalk/send/friendtalk-image` | 친구톡 이미지 |
+| POST | `/api/admin/barobill/kakaotalk/send/friendtalk-wide` | 친구톡 와이드 |
+| GET | `/api/admin/barobill/kakaotalk/send/{sendKey}` | 전송 결과 단건 |
+| POST | `/api/admin/barobill/kakaotalk/send/results` | 전송 결과 다건 |
+| DELETE | `/api/admin/barobill/kakaotalk/send/{sendKey}/cancel` | 예약 취소 |
+
+---
+
+## 5. WSDL 데이터 타입
+
+### 5.1 핵심 타입
+
+```
+KakaotalkChannel
+├── ChannelId       (string)  채널 ID (@로 시작)
+├── ChannelName     (string)  채널명
+└── Status          (int)     상태
+
+KakaotalkTemplate
+├── ChannelId       (string)  채널 ID
+├── TemplateName    (string)  템플릿 이름
+├── TemplateContent (string)  템플릿 본문
+├── TemplateExtra   (string)  부가 정보
+├── Status          (int)     검수 상태
+└── Buttons         (array)   버튼 목록
+
+KakaotalkATMessage (알림톡)
+├── ReceiverName    (string)  수신자 이름
+├── ReceiverNum     (string)  수신자 번호 (01012345678)
+├── Title           (string)  제목 (강조 표시용)
+├── Message         (string)  메시지 (템플릿 변수 치환 후)
+├── SmsMessage      (string)  SMS 대체 메시지
+└── SmsSubject      (string)  SMS 대체 제목
+
+KakaotalkFTMessage (친구톡)
+├── ReceiverName    (string)  수신자 이름
+├── ReceiverNum     (string)  수신자 번호
+├── Message         (string)  메시지 (자유 형식)
+├── SmsMessage      (string)  SMS 대체 메시지
+├── SmsSubject      (string)  SMS 대체 제목
+└── Buttons         (array)   버튼 목록
+
+KakaotalkButton
+├── Name            (string)  버튼 텍스트
+├── ButtonType      (string)  WL(웹링크), AL(앱링크), BK(봇키워드), MD(메시지전달)
+├── Url1            (string)  모바일 URL
+└── Url2            (string)  PC URL
+```
+
+---
+
+## 6. 메뉴 구조
+
+### 6.1 사이드바 메뉴
+
+```
+바로빌 > 카카오톡
+├── 카카오톡 (대시보드)    /barobill/kakaotalk
+├── 채널관리              /barobill/kakaotalk/channels
+├── 템플릿관리            /barobill/kakaotalk/templates
+├── 발송                  /barobill/kakaotalk/send
+├── 전송내역              /barobill/kakaotalk/history
+└── 사용법                /barobill/kakaotalk/guide
+```
+
+### 6.2 메뉴 DB 정보
+
+| 환경 | 부모 메뉴 ID (카카오톡) | 하위 메뉴 ID 범위 |
+|------|------------------------|-------------------|
+| 로컬 | 15614 | 15615 ~ 15619 |
+| 서버 | 15470 | 15471 ~ 15475 |
+
+---
+
+## 7. 다음 단계 (TODO)
+
+### 7.1 사전 준비 (비개발)
+
+1. [ ] 법인 명의 휴대폰으로 카카오톡 채널 개설
+2. [ ] 바로빌 관리자에서 카카오톡 서비스 신청
+3. [ ] 바로빌 채널 관리 URL에서 카카오 채널 연동
+4. [ ] 알림톡 템플릿 등록 및 카카오 검수 대기
+
+### 7.2 개발 (채널 연동 후)
+
+1. [ ] 테스트 서버에서 `GetKakaotalkChannels` 호출 → 채널 목록 확인
+2. [ ] `GetKakaotalkTemplates` 호출 → 템플릿 목록 확인
+3. [ ] 알림톡 테스트 발송 → 응답/상태 확인
+4. [ ] 친구톡 테스트 발송
+5. [ ] 에러 응답 코드 정리 및 핸들링 보강
+6. [ ] SMS 대체발송 테스트
+7. [ ] 대량 발송 테스트 (수신자 다건)
+8. [ ] 운영 서버 전환 (`testws` → `ws`)
+
+### 7.3 추후 고도화
+
+- [ ] 발송 이력 DB 저장 (현재는 바로빌 API 조회만)
+- [ ] 자동 발송 연동 (주문 확인, 배송 알림 등)
+- [ ] 발송 통계 대시보드
+- [ ] 엑셀 업로드 대량 발송
+- [ ] 주소록(고객 DB) 연동
+
+---
+
+## 8. 참고 자료
+
+- [바로빌 API 문서](https://dev.barobill.co.kr)
+- [카카오비즈니스 채널 관리](https://business.kakao.com)
+- [카카오 알림톡 가이드](https://kakaobusiness.gitbook.io)
+
+---
+
+## 변경 이력
+
+| 날짜 | 버전 | 변경 내용 |
+|------|------|----------|
+| 2026-02-14 | 0.1 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |