# 카카오톡 알림톡 채널 및 템플릿 등록 가이드

> **작성일**: 2026-02-20
> **상태**: 채널 등록 완료, 템플릿 심사 중
> **관련 문서**: [바로빌 카카오톡 연동](../features/barobill-kakaotalk/README.md), [전자계약 알림톡 연동 계획](../plans/esign-alimtalk-integration.md)

---

## 1. 진행 현황

| 단계 | 항목 | 상태 | 완료일 |
|------|------|------|--------|
| 1 | 카카오톡 비즈니스 채널 개설 | **완료** | 2026-02-20 |
| 2 | 바로빌에 카카오톡 채널 연동 | **완료** | 2026-02-20 |
| 3 | 알림톡 템플릿 등록 (카카오 심사 접수) | **심사 중** | 2026-02-20 접수 |
| 4 | 카카오 심사 승인 (영업일 기준 최대 3일) | **대기** | 예상: 2026-02-25 |
| 5 | 실 서비스 테스트 발송 | **대기** | 심사 승인 후 |
| 6 | 운영 전환 (test → production) | **대기** | 테스트 완료 후 |

---

## 2. 카카오톡 채널 정보

| 항목 | 값 |
|------|-----|
| **채널 ID** | `@codebridge` |
| **채널명** | (주)코드브릿지엑스 |
| **등록 플랫폼** | [카카오비즈니스](https://business.kakao.com) |
| **바로빌 연동** | 완료 (바로빌 카카오톡 > 채널관리에서 확인 가능) |
| **바로빌 관리 URL** | `test.barobill.co.kr/interop/kakaotalk_template.asp` |

### 2.1 채널 개설 절차 (완료)

1. [카카오비즈니스](https://business.kakao.com) 접속
2. 카카오톡 채널 > 새 채널 만들기
3. 채널명: `(주)코드브릿지엑스`, 검색용 ID: `@codebridge`
4. 사업자등록증 제출 및 인증 완료

### 2.2 바로빌 채널 연동 절차 (완료)

1. 바로빌 관리자 로그인 (test.barobill.co.kr)
2. 카카오톡 > 채널관리 메뉴 진입
3. "카카오톡 채널 관리" 탭에서 채널 `@codebridge` 연동
4. 채널 선택: `(주)코드브릿지엑스` 확인

---

## 3. 알림톡 템플릿 등록 내용

### 3.1 등록 시 주의사항

- 심사는 **영업일 기준 최대 3일** 소요 (카카오 검수)
- 템플릿은 **카카오톡 채널별로 각각** 등록해야 함
- **승인된 템플릿은 수정 불가** — 수정 필요 시 삭제 후 새로 등록
- 템플릿 작성 관련 자세한 사항은 [카카오톡 비즈니스 가이드](https://kakaobusiness.gitbook.io) 참조

### 3.2 템플릿 1: 전자계약_서명요청

| 항목 | 값 |
|------|-----|
| **템플릿명** | `전자계약_서명요청` |
| **용도** | 전자계약 서명 요청 시 서명자에게 발송 |
| **발송 시점** | 계약 발송 버튼 클릭 시 |

**템플릿 본문:**
```
안녕하세요, #{이름}님.
전자계약 서명 요청이 도착했습니다.

■ 계약명: #{계약명}
■ 서명 기한: #{기한}

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

**버튼 설정:**

| 항목 | 값 |
|------|-----|
| 버튼명 | `계약서 확인하기` |
| 버튼 타입 | 웹링크 (WL) |
| Url1 (모바일) | `https://mng.codebridge-x.com` |
| Url2 (PC) | `https://mng.codebridge-x.com` |

> 실제 발송 시 코드에서 `https://mng.codebridge-x.com/esign/sign/{access_token}` 형태의 동적 URL로 치환됨

### 3.3 템플릿 2: 전자계약_리마인드

| 항목 | 값 |
|------|-----|
| **템플릿명** | `전자계약_리마인드` |
| **용도** | 미서명자에게 리마인더 발송 |
| **발송 시점** | 관리자가 리마인더 발송 버튼 클릭 시 |

**템플릿 본문:**
```
안녕하세요, #{이름}님.
아직 서명이 완료되지 않은 전자계약이 있습니다.

■ 계약명: #{계약명}
■ 서명 기한: #{기한}

기한 내에 서명을 완료해 주세요.
```

**버튼 설정:**

| 항목 | 값 |
|------|-----|
| 버튼명 | `서명하기` |
| 버튼 타입 | 웹링크 (WL) |
| Url1 (모바일) | `https://mng.codebridge-x.com` |
| Url2 (PC) | `https://mng.codebridge-x.com` |

### 3.4 템플릿 3: 전자계약_완료 (추후 등록 예정)

| 항목 | 값 |
|------|-----|
| **템플릿명** | `전자계약_완료` |
| **용도** | 모든 서명 완료 시 서명자들에게 완료 알림 |
| **발송 시점** | 마지막 서명자 서명 완료 시 자동 발송 |

**템플릿 본문:**
```
안녕하세요, #{이름}님.
전자계약이 모든 서명자의 서명 완료로 확정되었습니다.

■ 계약명: #{계약명}
■ 완료일: #{완료일}

아래 버튼에서 서명 완료된 계약서를 확인할 수 있습니다.
```

**버튼 설정:**

| 항목 | 값 |
|------|-----|
| 버튼명 | `계약서 확인하기` |
| 버튼 타입 | 웹링크 (WL) |
| Url1 (모바일) | `https://mng.codebridge-x.com` |
| Url2 (PC) | `https://mng.codebridge-x.com` |

---

## 4. 코드와 템플릿 매핑

### 4.1 변수 매핑 (코드 → 템플릿)

| 템플릿 변수 | PHP 코드 변수 | 설명 |
|-------------|--------------|------|
| `#{이름}` | `$signer->name` | 서명자 이름 |
| `#{계약명}` | `$contract->title` | 전자계약 제목 |
| `#{기한}` | `$contract->expires_at->format('Y-m-d H:i')` | 서명 만료 기한 |
| `#{완료일}` | `now()->format('Y-m-d H:i')` | 서명 완료 일시 |

### 4.2 발송 코드 위치

| 구분 | 파일 | 메서드 | 라인 |
|------|------|--------|------|
| 알림톡 발송 | `app/Http/Controllers/ESign/EsignApiController.php` | `sendAlimtalk()` | 951~1020 |
| 서명 요청 발송 | 동일 파일 | `send()` | 754~826 |
| 리마인더 발송 | 동일 파일 | `remind()` | 831~901 |
| 메시지 생성 | 동일 파일 | `sendAlimtalk()` 내부 | 973~977 |

### 4.3 SMS 대체발송

알림톡 발송 실패 시 (카카오톡 미사용자 등) SMS로 자동 대체 발송됨:

```
[SAM] {이름}님, 전자계약 서명 요청이 도착했습니다. {서명URL}
```

---

## 5. 서버 환경 설정

### 5.1 APP_URL 확인 필수

서명 URL은 `config('app.url')` 값을 사용하여 생성됨:

```
서명 URL = config('app.url') + '/esign/sign/' + access_token
         = https://mng.codebridge-x.com/esign/sign/abc123...
```

서버의 `.env` 파일에서 확인:
```env
APP_URL=https://mng.codebridge-x.com
```

### 5.2 바로빌 서버 모드

| 환경 | WSDL URL | 설정 |
|------|----------|------|
| **테스트** | `https://testws.baroservice.com/KAKAOTALK.asmx?WSDL` | `is_test_mode = true` |
| **운영** | `https://ws.baroservice.com/KAKAOTALK.asmx?WSDL` | `is_test_mode = false` |

현재 테스트 모드로 운영 중. 심사 승인 및 테스트 완료 후 운영 모드로 전환 예정.

---

## 6. 심사 승인 후 작업 (TODO)

- [ ] 카카오 템플릿 심사 승인 확인
- [ ] 바로빌 템플릿 관리 페이지에서 승인 상태 확인
- [ ] 테스트 발송 실행 (내부 번호로)
- [ ] SMS 대체발송 테스트
- [ ] 운영 모드 전환 (`is_test_mode = false`)
- [ ] 전자계약_완료 템플릿 추가 등록

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2026-02-20 | 카카오톡 채널 등록 완료, 알림톡 템플릿 2종 심사 접수, 문서 작성 |
