# 바로빌 카카오톡 (알림톡/친구톡) 연동

> **문서 버전**: 0.1 (초안)
> **작성일**: 2026-02-14
> **최종 수정**: 2026-02-14
> **상태**: 개발 중 (사전 준비 단계)
> **대상 프로젝트**: MNG

---

## 1. 개요

### 1.1 목적

바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여,
고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다.

### 1.2 사전 요구사항

| 항목 | 상태 | 설명 |
|------|------|------|
| 법인 명의 휴대폰 준비 | **완료** | 카카오톡 채널 가입에 법인 명의 번호 사용 |
| 카카오톡 채널 개설 | **완료** (2026-02-20) | 채널 ID: `@codebridge`, 채널명: (주)코드브릿지엑스 |
| 바로빌 카카오톡 서비스 신청 | **완료** (2026-02-20) | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
| 채널 연동 (바로빌↔카카오) | **완료** (2026-02-20) | 바로빌 관리 URL에서 채널 연동 처리 |
| 알림톡 템플릿 등록/검수 | **심사 중** (2026-02-20 접수) | 2종 접수, 카카오 검수 영업일 기준 최대 3일 |

> 상세 등록 가이드: [카카오톡 알림톡 채널 및 템플릿 등록 가이드](../../guides/카카오톡-알림톡-채널-템플릿-등록.md)

### 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. 활용 계획: 전자계약(E-Sign) 알림톡 연동

> **상세 구현 계획서**: [plans/esign-alimtalk-integration.md](../../plans/esign-alimtalk-integration.md)
> UI/UX 변경, 백엔드 로직, DB 변경, 카카오 템플릿 3종, 구현 순서 등 포함

### 8.1 배경

현재 전자계약은 **이메일**로 발송하고 있으나, 열람률이 낮고 확인이 지연되는 문제가 있다.
카카오톡 알림톡으로 전환하면 즉시 알림이 도달하여 계약 체결 속도를 크게 개선할 수 있다.

### 8.2 발송 흐름

```
전자계약 생성 (E-Sign)
    │
    ├─ [기존] 이메일 발송
    │
    └─ [추가] 알림톡 발송 (SendATKakaotalkEx)
           │
           ├─ 메시지: "{회사명}에서 전자계약서가 도착했습니다."
           ├─ 내용: 계약명, 발신자, 마감일 등
           └─ 버튼: [계약서 확인하기] → 전자서명 페이지 URL
                     (ButtonType: WL, 웹링크)
```

### 8.3 알림톡 템플릿 (안)

```
[전자계약 도착 안내]

안녕하세요, #{수신자명}님.
#{발신회사명}에서 전자계약서가 도착했습니다.

■ 계약명: #{계약명}
■ 발신자: #{발신자명}
■ 마감일: #{마감일}

아래 버튼을 눌러 계약서를 확인하고 서명해주세요.

[계약서 확인하기]  ← 웹링크 버튼
```

> 카카오 템플릿 검수 시 정보성 메시지로 분류되어 승인 가능성 높음

### 8.4 기술 구현 포인트

| 항목 | 내용 |
|------|------|
| **사용 API** | `SendATKakaotalkEx` (버튼 포함 알림톡) |
| **버튼 타입** | `WL` (웹링크) - 모바일/PC URL 모두 설정 |
| **SMS 대체발송** | 카카오톡 미사용자에게 자동 SMS 전환 |
| **구현 위치** | 전자계약 발송 컨트롤러에서 `BarobillService::sendATKakaotalkEx()` 호출 추가 |
| **이메일 병행** | 알림톡 + 이메일 동시 발송 (선택 가능하게) |

### 8.5 기대 효과

- **열람률 향상**: 이메일(20~30%) → 카카오톡(80%+)
- **체결 속도**: 이메일 확인 지연(수시간~1일) → 카카오톡 즉시 확인
- **접근성**: 별도 앱 설치 없이 카카오톡에서 바로 계약서 페이지 이동
- **미사용자 대응**: SMS 대체발송으로 카카오톡 미사용자도 커버

### 8.6 준비 순서

| 순서 | 내용 | 비고 |
|------|------|------|
| 1 | 카카오 채널 개설 | 법인 명의 휴대폰 필요 |
| 2 | 바로빌에 채널 연동 | 바로빌 관리 페이지 |
| 3 | "전자계약 도착 안내" 템플릿 등록 | 카카오 검수 1~3 영업일 |
| 4 | 전자계약 컨트롤러에 알림톡 발송 로직 추가 | 코드 구현 |
| 5 | 테스트 발송 → 운영 전환 | testws → ws |

---

## 9. 참고 자료

- [바로빌 API 문서](https://dev.barobill.co.kr)
- [카카오비즈니스 채널 관리](https://business.kakao.com)
- [카카오 알림톡 가이드](https://kakaobusiness.gitbook.io)

---

## 변경 이력

| 날짜 | 버전 | 변경 내용 |
|------|------|----------|
| 2026-02-14 | 0.2 | 전자계약(E-Sign) 알림톡 연동 활용 계획 추가 |
| 2026-02-14 | 0.1 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |