docs: [barobill-kakaotalk] 알림톡 연동 완료 문서화 (트러블슈팅, v2 템플릿 가이드)

2026-02-24 19:44:05 +09:00
parent 95bbc90f93
commit 34f9cf41e7
1 changed files with 289 additions and 222 deletions
--- a/features/barobill-kakaotalk/README.md
+++ b/features/barobill-kakaotalk/README.md
@@ -1,9 +1,9 @@
 # 바로빌 카카오톡 (알림톡/친구톡) 연동
-> **문서 버전**: 0.1 (초안)
+> **문서 버전**: 1.0
 > **작성일**: 2026-02-14
-> **최종 수정**: 2026-02-14
+> **최종 수정**: 2026-02-24
-> **상태**: 개발 중 (사전 준비 단계)
+> **상태**: 운영 중 (전자계약 알림톡 발송 완료)
 > **대상 프로젝트**: MNG
 ---
@@ -23,7 +23,9 @@
 | 카카오톡 채널 개설 | **완료** (2026-02-20) | 채널 ID: `@codebridge`, 채널명: (주)코드브릿지엑스 |
 | 바로빌 카카오톡 서비스 신청 | **완료** (2026-02-20) | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
 | 채널 연동 (바로빌↔카카오) | **완료** (2026-02-20) | 바로빌 관리 URL에서 채널 연동 처리 |
-| 알림톡 템플릿 등록/검수 | **심사 중** (2026-02-20 접수) | 2종 접수, 카카오 검수 영업일 기준 최대 3일 |
+| 바로빌 파트너 과금 설정 | **완료** (2026-02-23) | 바로빌 측에서 파트너사 과금 설정 완료 |
 | 알림톡 템플릿 v1 검수 | **완료** (2026-02-22) | `전자계약_서명요청`, `전자계약_리마인드` 2종 승인 |
 | 알림톡 템플릿 v2 검수 | **심사 중** (2026-02-24 접수) | 버튼 URL에 `#{토큰}` 변수 포함 2종 재등록 |
 > 상세 등록 가이드: [카카오톡 알림톡 채널 및 템플릿 등록 가이드](../../guides/카카오톡-알림톡-채널-템플릿-등록.md)
@@ -51,8 +53,11 @@ SAM MNG (브라우저)
    ├─ [페이지] /barobill/kakaotalk/*          ← Blade 뷰
    │      KakaotalkController (페이지 렌더링)
    │
-    └─ [API]  /api/admin/barobill/kakaotalk/*   ← AJAX 호출
+    ├─ [API]  /api/admin/barobill/kakaotalk/*   ← AJAX 호출
-           BarobillKakaotalkController
+    │      BarobillKakaotalkController
    │
    └─ [전자계약] /esign/*                      ← 자동 발송
           EsignApiController::sendAlimtalk()
                │
                └─ BarobillService (SOAP 클라이언트)
                       │
@@ -70,47 +75,293 @@ SAM MNG (브라우저)
 ---
-## 3. 구현 현황
+## 3. 전자계약 알림톡 연동 (핵심)
-### 3.1 완료된 항목
+### 3.1 발송 흐름
-| 구분 | 파일 | 설명 |
+```
-|------|------|------|
+전자계약 생성 (E-Sign)
-| SOAP 서비스 | `app/Services/Barobill/BarobillService.php` | kakaotalk SOAP 클라이언트 + 15개 API 메서드 추가 |
+    │
-| API 컨트롤러 | `app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php` | 15개 API 엔드포인트 |
+    ├─ [1단계] EsignApiController::sendAlimtalk()
-| 페이지 컨트롤러 | `app/Http/Controllers/Barobill/KakaotalkController.php` | 6개 페이지 (index, channels, templates, send, history, guide) |
+    │      │
-| 라우트 (web) | `routes/web.php` | `/barobill/kakaotalk/*` 6개 라우트 |
+    │      ├─ 채널 ID 조회 (getKakaotalkChannelId)
-| 라우트 (api) | `routes/api.php` | `/api/admin/barobill/kakaotalk/*` 14개 라우트 |
+    │      ├─ 템플릿 본문 + 버튼 조회 (getTemplateData)
-| 대시보드 뷰 | `views/barobill/kakaotalk/index.blade.php` | 채널 상태 요약, 빠른 메뉴 |
+    │      ├─ 변수 치환 (#{이름}, #{계약명}, #{기한})
-| 채널 관리 뷰 | `views/barobill/kakaotalk/channels/index.blade.php` | 채널 목록, 관리 URL 연결 |
+    │      └─ SendATKakaotalkEx 호출
-| 템플릿 관리 뷰 | `views/barobill/kakaotalk/templates/index.blade.php` | 채널별 템플릿 조회, 상세 모달 |
+    │
-| 발송 뷰 | `views/barobill/kakaotalk/send/index.blade.php` | 알림톡/친구톡 탭, 발송 폼 |
+    ├─ [2단계] 바로빌 접수 → SendKey 반환
-| 전송내역 뷰 | `views/barobill/kakaotalk/history/index.blade.php` | 전송키 조회, 예약 취소 |
+    │
-| 사용법 가이드 뷰 | `views/barobill/kakaotalk/guide.blade.php` | 초보자용 8단계 가이드 |
+    ├─ [3단계] 3초 대기 후 GetSendKakaotalk으로 전달 결과 확인
-| 메뉴 등록 | DB (menus 테이블) | 로컬/서버 모두 등록 완료 |
+    │      │
    │      ├─ ResultCode = 1 → 성공
    │      └─ ResultCode != 1 → 실패 (에러 반환)
    │
    └─ [이메일 폴백] 알림톡 실패 시 이메일로 자동 전환
 ```
-### 3.2 미완료 / 검증 필요 항목
+### 3.2 등록된 템플릿 (v1 — 현재 운영)
-| 항목 | 상태 | 비고 |
+**`전자계약_서명요청`**
-|------|------|------|
+
-| 채널 API 실제 호출 테스트 | **대기** | 카카오 채널 개설 후 가능 |
+```
-| 템플릿 조회 테스트 | **대기** | 템플릿 등록/검수 후 가능 |
+ 안녕하세요, #{이름}님.
-| 알림톡 발송 테스트 | **대기** | 채널+템플릿 준비 후 가능 |
+ 전자계약 서명 요청이 도착했습니다.
-| 친구톡 발송 테스트 | **대기** | 채널 친구 추가 후 가능 |
+
-| SMS 대체발송 테스트 | **대기** | 바로빌 SMS 서비스 활성화 필요 |
+ ■ 계약명: #{계약명}
-| 대량 발송 테스트 | **대기** | 단건 테스트 완료 후 |
+ ■ 서명 기한: #{기한}
-| 에러 핸들링 고도화 | **대기** | 실제 API 응답 확인 후 개선 |
+
 아래 버튼을 눌러 계약서를 확인하고 서명해 주세요.
 ```
 - 버튼: `계약서 확인하기` (WL)
 - Url1/Url2: `https://mng.codebridge-x.com`
 **`전자계약_리마인드`**
 ```
 안녕하세요, #{이름}님.
 아직 서명이 완료되지 않은 전자계약이 있습니다.
 ■ 계약명: #{계약명}
 ■ 서명 기한: #{기한}
 기한 내에 서명을 완료해 주세요.
 ```
 - 버튼: `계약서 확인하기` (WL)
 - Url1/Url2: `https://mng.codebridge-x.com`
 ### 3.3 등록 예정 템플릿 (v2 — 심사 중)
 > **2026-02-24 재등록**: 버튼 URL에 `#{토큰}` 변수를 포함하여 동적 서명 URL 지원
 - Url1/Url2: `https://mng.codebridge-x.com/esign/sign/#{토큰}`
 v2 승인 후 코드 변경 필요:
 - `EsignApiController::sendAlimtalk()`에서 동적 `$signUrl`을 버튼 URL로 전달
 - 현재 코드의 등록된 URL 그대로 사용 → 동적 URL 사용으로 전환
 ### 3.4 임시 우회: 로그인 페이지 서명 확인
 v1 템플릿의 버튼 URL이 대시보드(`https://mng.codebridge-x.com`)로 고정되어 있어,
 로그인 페이지에 전화번호 기반 서명 확인 기능을 추가하였다.
 ```
 알림톡 버튼 클릭 → https://mng.codebridge-x.com → 로그인 페이지
    │
    └─ "전자계약 서명하기" 섹션
           │
           ├─ 전화번호 입력
           ├─ POST /esign/verify-phone
           └─ 대기 중인 계약 조회 → /esign/sign/{token} 리다이렉트
 ```
 - 라우트: `POST /esign/verify-phone`
 - 컨트롤러: `EsignPublicController::verifyPhone()`
 - v2 템플릿 승인 후에도 유지 (비로그인 사용자 대응)
 ### 3.5 관련 파일
 | 파일 | 역할 |
 |------|------|
 | `app/Http/Controllers/ESign/EsignApiController.php` | `sendAlimtalk()`, `getTemplateData()` |
 | `app/Http/Controllers/ESign/EsignPublicController.php` | `verifyPhone()` 전화번호 확인 |
 | `app/Services/Barobill/BarobillService.php` | SOAP 클라이언트, `sendATKakaotalkEx()` |
 | `resources/views/auth/login.blade.php` | 로그인 페이지 서명 확인 UI |
 | `routes/web.php` | `/esign/verify-phone` 라우트 |
 ---
-## 4. API 메서드 목록
+## 4. 트러블슈팅 (실전 경험)
-### 4.1 BarobillService 카카오톡 메서드
+> **경고: 아래 내용은 실제 연동 과정에서 발견한 핵심 이슈다. 반드시 숙지할 것.**
 ### 4.1 바로빌 API 응답 구조
 바로빌 SOAP 응답은 `stdClass` 객체로 반환된다. 배열이 아니므로 주의:
 ```php
 // ❌ 잘못된 접근
 $channels = $result['data']; // 배열이 아님
 // ✅ 올바른 접근
 $data = $result['data']; // stdClass
 $channels = is_array($data->KakaotalkChannel)
    ? $data->KakaotalkChannel
    : [$data->KakaotalkChannel]; // 1건이면 객체, N건이면 배열
 ```
 ### 4.2 SendKey vs ResultCode (2단계 검증 필수)
 > **핵심**: 바로빌이 SendKey를 반환해도 **실제 카카오톡 전달이 실패할 수 있다.**
 ```
 [1단계] SendATKakaotalkEx 호출
    → SendKey 반환 (예: BB_6648603713_AT_3044107_260224)
    → 이것은 "접수 성공"이지 "전달 성공"이 아님!
 [2단계] 3초 후 GetSendKakaotalk(SendKey) 호출
    → ResultCode = 1: 전달 성공 ✅
    → ResultCode = 4: 템플릿 데이터 일치 오류 ❌
    → ResultCode != 1: 기타 실패 ❌
 ```
 ```php
 // 반드시 2단계 검증 필요
 if ($result['success'] && is_string($result['data'])) {
    $sendKey = $result['data'];
    sleep(3); // 카카오톡 전달 대기
    $sendResult = $barobill->getSendKakaotalk($member->biz_no, $sendKey);
    $resultCode = $sendResult['data']->ResultCode ?? null;
    if ($resultCode != 1) {
        // 실패 처리!
    }
 }
 ```
 ### 4.3 템플릿 URL 정확 일치 규칙
 > **핵심**: 버튼 URL은 등록된 템플릿의 URL과 **정확히 일치**해야 한다. 1글자라도 다르면 실패.
 | 등록된 URL | 전송 시 URL | 결과 |
 |------------|------------|------|
 | `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com` | ResultCode=1 (성공) |
 | `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com/esign/sign/xxx` | ResultCode=4 (실패) |
 | `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com?sign=xxx` | ResultCode=4 (실패) |
 | `https://mng.codebridge-x.com` | `https://mng.codebridge-x.com#sign=xxx` | ResultCode=4 (실패) |
 - 경로 추가: 실패
 - 쿼리 파라미터 추가: 실패
 - URL 프래그먼트(#) 추가: 실패
 - **동적 URL을 사용하려면 템플릿에 `#{변수}` 포함하여 재등록 필요**
 ### 4.4 SmsReply 오류 (-31325)
 `SmsReply` 파라미터가 `'S'`(대체발송 사용)인데 `SmsSenderNum`이 비어있으면 `-31325` 오류 발생.
 ```php
 // ❌ 오류 발생
 'SmsReply' => empty($smsMessage) ? 'N' : 'S', // SmsSenderNum이 비어도 S로 설정
 // ✅ 수정
 'SmsReply' => (empty($smsMessage) || empty($smsSenderNum)) ? 'N' : 'S',
 ```
 ### 4.5 SOAP 파라미터 구조
 바로빌 SOAP API의 파라미터 구조에 주의:
 ```php
 // 올바른 구조
 $params = [
    'CorpNum' => $bizNo,         // 사업자번호 (하이픈 포함: 123-45-67890)
    'SenderID' => $barobillId,   // 바로빌 계정 ID
    'YellowId' => $channelId,    // 카카오 채널 ID (@codebridge)
    'TemplateName' => '전자계약_서명요청',
    'SendDT' => '',              // 즉시발송: 빈 문자열
    'SmsReply' => 'N',           // SMS 발신번호 없으면 반드시 'N'
    'SmsSenderNum' => '',
    'KakaotalkMessage' => [
        'ReceiverName' => $name,
        'ReceiverNum' => $phone,  // 하이픈 없이: 01012345678
        'Title' => '',
        'Message' => $message,    // 템플릿 변수 치환 완료된 본문
        'SmsMessage' => '',
        'SmsSubject' => '',
        'Buttons' => ['KakaotalkButton' => $buttons], // 버튼 배열
    ],
 ];
 ```
 ### 4.6 에러 코드 정리
 | 코드 | 메시지 | 원인 | 해결 |
 |------|--------|------|------|
 | 1 | 성공 | 정상 전달 | - |
 | 4 | 템플릿 데이터 일치 오류 | 본문/버튼 URL이 등록 템플릿과 불일치 | 등록된 템플릿과 동일하게 전송 |
 | -31325 | 대체문자 유형 오류 | SmsReply=S인데 SmsSenderNum 비어있음 | SmsReply를 N으로 설정 |
 | 음수값 | 바로빌 API 오류 | 파라미터 오류 또는 서비스 미설정 | 바로빌 에러코드 문서 참조 |
 ---
 ## 5. 구현 현황
 ### 5.1 완료된 항목
 | 구분 | 파일 | 설명 |
 |------|------|------|
 | SOAP 서비스 | `app/Services/Barobill/BarobillService.php` | kakaotalk SOAP 클라이언트 + 15개 API 메서드 |
 | 전자계약 알림톡 | `app/Http/Controllers/ESign/EsignApiController.php` | `sendAlimtalk()`, `getTemplateData()` |
 | 서명 확인 | `app/Http/Controllers/ESign/EsignPublicController.php` | `verifyPhone()` 전화번호 기반 서명 확인 |
 | API 컨트롤러 | `app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php` | 15개 API 엔드포인트 |
 | 페이지 컨트롤러 | `app/Http/Controllers/Barobill/KakaotalkController.php` | 6개 관리 페이지 |
 | 로그인 페이지 | `resources/views/auth/login.blade.php` | 전자계약 서명하기 섹션 |
 | 라우트 | `routes/web.php` | `/esign/verify-phone`, `/barobill/kakaotalk/*` |
 | 메뉴 등록 | DB (menus 테이블) | 로컬/서버 모두 등록 완료 |
 ### 5.2 검증 완료 항목
 | 항목 | 결과 | 날짜 |
 |------|------|------|
 | 채널 API 호출 | **성공** | 2026-02-22 |
 | 템플릿 조회 | **성공** | 2026-02-22 |
 | 알림톡 발송 (본문) | **성공** (ResultCode=1) | 2026-02-24 |
 | 알림톡 버튼 URL | **성공** (등록된 URL 사용 시) | 2026-02-24 |
 | 전달 결과 확인 (2단계) | **구현 완료** | 2026-02-24 |
 | 로그인 페이지 서명 확인 | **성공** | 2026-02-24 |
 ### 5.3 대기 중인 항목
 | 항목 | 상태 | 비고 |
 |------|------|------|
 | 템플릿 v2 승인 | **심사 중** | 버튼 URL에 `#{토큰}` 변수 포함 |
 | v2 승인 후 코드 수정 | **대기** | 동적 서명 URL을 버튼에 전달 |
 | `전자계약_완료` 템플릿 | **미등록** | 서명 완료 알림 발송용 |
 | SMS 대체발송 | **미설정** | 발신번호 등록 필요 |
 | 친구톡 발송 | **대기** | 채널 친구 추가 후 가능 |
 | 대량 발송 | **대기** | 단건 안정화 후 |
 ---
 ## 6. v2 템플릿 승인 후 코드 변경 가이드
 ### 6.1 변경 대상
 `EsignApiController::sendAlimtalk()` (약 1059~1063행)
 ### 6.2 현재 코드 (v1)
 ```php
 // 등록된 버튼 URL을 그대로 사용 (동적 URL 사용 시 템플릿 불일치 오류)
 $buttons = ! empty($templateButtons) ? $templateButtons : [
    ['Name' => '계약서 확인하기', 'ButtonType' => 'WL',
     'Url1' => 'https://mng.codebridge-x.com', 'Url2' => 'https://mng.codebridge-x.com'],
 ];
 ```
 ### 6.3 변경 코드 (v2 승인 후)
 ```php
 // v2 템플릿: 버튼 URL에 동적 서명 URL 사용
 $buttons = [
    ['Name' => '계약서 확인하기', 'ButtonType' => 'WL',
     'Url1' => $signUrl, 'Url2' => $signUrl],
 ];
 ```
 - `$signUrl`은 1033행에서 이미 생성됨: `config('app.url').'/esign/sign/'.$signer->access_token`
 - `getTemplateData()`에서 등록된 버튼 조회는 더 이상 필요 없음 (제거 가능)
 ---
 ## 7. API 메서드 목록
 ### 7.1 BarobillService 카카오톡 메서드
 | 메서드 | SOAP Action | 설명 |
 |--------|-------------|------|
 | `getKakaotalkChannels` | `GetKakaotalkChannels` | 채널 목록 조회 |
-| `getKakaotalkChannelManagementUrl` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL (바로빌 페이지) |
+| `getKakaotalkChannelManagementUrl` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL |
 | `getKakaotalkTemplates` | `GetKakaotalkTemplates` | 템플릿 목록 조회 |
 | `getKakaotalkTemplateManagementUrl` | `GetKakaotalkTemplateManagementURL` | 템플릿 관리 URL |
 | `sendATKakaotalk` | `SendATKakaotalk` | 알림톡 단건 발송 |
@@ -124,199 +375,14 @@ SAM MNG (브라우저)
 | `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 데이터 타입
+## 8. 참고 자료
 ### 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)
 - 바로빌 템플릿 관리: 로그인 후 `https://www.barobill.co.kr` → 카카오톡 템플릿 관리
 ---
@@ -324,5 +390,6 @@ KakaotalkButton
 | 날짜 | 버전 | 변경 내용 |
 |------|------|----------|
 | 2026-02-24 | 1.0 | 전자계약 알림톡 연동 완료, 트러블슈팅 문서화, v2 템플릿 가이드 추가 |
 | 2026-02-14 | 0.2 | 전자계약(E-Sign) 알림톡 연동 활용 계획 추가 |
 | 2026-02-14 | 0.1 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |