SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs:카카오톡 알림톡 채널 등록 완료 기록 및 템플릿 등록 가이드 작성

Browse Source 
- 카카오톡 채널(@codebridge) 개설 및 바로빌 연동 완료 상태 반영
- 알림톡 템플릿 2종(서명요청, 리마인드) 심사 접수 내용 기록
- 코드-템플릿 변수 매핑, 서버 환경 설정, 심사 후 TODO 포함

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
김보곤
2026-02-20 14:44:15 +09:00
parent 6c3c16c66b
commit bbcb9406db
2 changed files with 225 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
features/barobill-kakaotalk/README.md
View File

@@ -15,15 +15,17 @@
바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여,
고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다.
### 1.2 사전 요구사항 (미완료)
### 1.2 사전 요구사항
| 항목 | 상태 | 설명 |
|------|------|------|
| 법인 명의 휴대폰 준비 | **대기** | 카카오톡 채널 가입에 법인 명의 번호 필요 |
| 카카오톡 채널 개설 | **대기** | [카카오비즈니스](https://business.kakao.com) 에서 채널 생성 |
| 바로빌 카카오톡 서비스 신청 | **대기** | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
| 채널 연동 (바로빌↔카카오) | **대기** | 바로빌 관리 URL에서 채널 연동 처리 |
| 알림톡 템플릿 등록/검수 | **대기** | 카카오 검수 승인 필요 (1~3 영업일) |
| 법인 명의 휴대폰 준비 | **완료** | 카카오톡 채널 가입에 법인 명의 번호 사용 |
| 카카오톡 채널 개설 | **완료** (2026-02-20) | 채널 ID: `@codebridge`, 채널명: (주)코드브릿지엑스 |
| 바로빌 카카오톡 서비스 신청 | **완료** (2026-02-20) | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 |
| 채널 연동 (바로빌↔카카오) | **완료** (2026-02-20) | 바로빌 관리 URL에서 채널 연동 처리 |
| 알림톡 템플릿 등록/검수 | **심사 중** (2026-02-20 접수) | 2종 접수, 카카오 검수 영업일 기준 최대 3일 |
> 상세 등록 가이드: [카카오톡 알림톡 채널 및 템플릿 등록 가이드](../../guides/카카오톡-알림톡-채널-템플릿-등록.md)
### 1.3 알림톡 vs 친구톡

217
guides/카카오톡-알림톡-채널-템플릿-등록.md Normal file
View File

@@ -0,0 +1,217 @@
# 카카오톡 알림톡 채널 및 템플릿 등록 가이드
> **작성일**: 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종 심사 접수, 문서 작성 |