From bbcb9406dbddeff3c90a4f55c2aef64c4654f5e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Fri, 20 Feb 2026 14:44:15 +0900 Subject: [PATCH] =?UTF-8?q?docs:=EC=B9=B4=EC=B9=B4=EC=98=A4=ED=86=A1=20?= =?UTF-8?q?=EC=95=8C=EB=A6=BC=ED=86=A1=20=EC=B1=84=EB=84=90=20=EB=93=B1?= =?UTF-8?q?=EB=A1=9D=20=EC=99=84=EB=A3=8C=20=EA=B8=B0=EB=A1=9D=20=EB=B0=8F?= =?UTF-8?q?=20=ED=85=9C=ED=94=8C=EB=A6=BF=20=EB=93=B1=EB=A1=9D=20=EA=B0=80?= =?UTF-8?q?=EC=9D=B4=EB=93=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 카카오톡 채널(@codebridge) 개설 및 바로빌 연동 완료 상태 반영 - 알림톡 템플릿 2종(서명요청, 리마인드) 심사 접수 내용 기록 - 코드-템플릿 변수 매핑, 서버 환경 설정, 심사 후 TODO 포함 Co-Authored-By: Claude Opus 4.6 --- features/barobill-kakaotalk/README.md | 14 +- guides/카카오톡-알림톡-채널-템플릿-등록.md | 217 +++++++++++++++++++++ 2 files changed, 225 insertions(+), 6 deletions(-) create mode 100644 guides/카카오톡-알림톡-채널-템플릿-등록.md diff --git a/features/barobill-kakaotalk/README.md b/features/barobill-kakaotalk/README.md index 13edb95..88466e9 100644 --- a/features/barobill-kakaotalk/README.md +++ b/features/barobill-kakaotalk/README.md @@ -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 친구톡 diff --git a/guides/카카오톡-알림톡-채널-템플릿-등록.md b/guides/카카오톡-알림톡-채널-템플릿-등록.md new file mode 100644 index 0000000..c61d113 --- /dev/null +++ b/guides/카카오톡-알림톡-채널-템플릿-등록.md @@ -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종 심사 접수, 문서 작성 |