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 호출
-           BarobillKakaotalkController
+    ├─ [API]  /api/admin/barobill/kakaotalk/*   ← AJAX 호출
+    │      BarobillKakaotalkController
+    │
+    └─ [전자계약] /esign/*                      ← 자동 발송
+           EsignApiController::sendAlimtalk()
                │
                └─ BarobillService (SOAP 클라이언트)
                       │
@@ -70,47 +75,293 @@ SAM MNG (브라우저)

 ---

-## 3. 구현 현황
+## 3. 전자계약 알림톡 연동 (핵심)

-### 3.1 완료된 항목
+### 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 테이블) | 로컬/서버 모두 등록 완료 |
+```
+전자계약 생성 (E-Sign)
+    │
+    ├─ [1단계] EsignApiController::sendAlimtalk()
+    │      │
+    │      ├─ 채널 ID 조회 (getKakaotalkChannelId)
+    │      ├─ 템플릿 본문 + 버튼 조회 (getTemplateData)
+    │      ├─ 변수 치환 (#{이름}, #{계약명}, #{기한})
+    │      └─ SendATKakaotalkEx 호출
+    │
+    ├─ [2단계] 바로빌 접수 → SendKey 반환
+    │
+    ├─ [3단계] 3초 대기 후 GetSendKakaotalk으로 전달 결과 확인
+    │      │
+    │      ├─ 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 데이터 타입
-
-### 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. 참고 자료
+## 8. 참고 자료

 - [바로빌 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 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |