Files

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

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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-20 14:44:15 +09:00

13 KiB

Raw Blame History

바로빌 카카오톡 (알림톡/친구톡) 연동

문서 버전: 0.1 (초안) 작성일: 2026-02-14 최종 수정: 2026-02-14 상태: 개발 중 (사전 준비 단계) 대상 프로젝트: MNG

1. 개요

1.1 목적

바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여, 고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다.

1.2 사전 요구사항

항목	상태	설명
법인 명의 휴대폰 준비	완료	카카오톡 채널 가입에 법인 명의 번호 사용
카카오톡 채널 개설	완료 (2026-02-20)	채널 ID: `@codebridge`, 채널명: (주)코드브릿지엑스
바로빌 카카오톡 서비스 신청	완료 (2026-02-20)	바로빌 관리자 페이지에서 카카오톡 서비스 활성화
채널 연동 (바로빌↔카카오)	완료 (2026-02-20)	바로빌 관리 URL에서 채널 연동 처리
알림톡 템플릿 등록/검수	심사 중 (2026-02-20 접수)	2종 접수, 카카오 검수 영업일 기준 최대 3일

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

1.3 알림톡 vs 친구톡

구분	알림톡	친구톡
용도	정보성 메시지 (주문확인, 배송안내 등)	광고성 메시지 (프로모션, 이벤트 등)
수신 대상	모든 카카오톡 사용자	채널 친구 추가한 사용자만
템플릿	필수 (카카오 사전 검수)	불필요 (자유 형식)
광고 표시	불가	필수 (`(광고)` 표기)
이미지 첨부	불가	가능 (이미지/와이드 이미지)
비용	건당 약 8~9원	건당 약 15~20원
SMS 대체발송	설정 가능	설정 가능

2. 아키텍처

2.1 시스템 구조

SAM MNG (브라우저)
    │
    ├─ [페이지] /barobill/kakaotalk/*          ← Blade 뷰
    │      KakaotalkController (페이지 렌더링)
    │
    └─ [API]  /api/admin/barobill/kakaotalk/*   ← AJAX 호출
           BarobillKakaotalkController
                │
                └─ BarobillService (SOAP 클라이언트)
                       │
                       └─ 바로빌 KAKAOTALK.asmx (WSDL)
                              │
                              └─ 카카오톡 서버

2.2 바로빌 SOAP API 엔드포인트

환경	WSDL URL
테스트	`https://testws.baroservice.com/KAKAOTALK.asmx?WSDL`
운영	`https://ws.baroservice.com/KAKAOTALK.asmx?WSDL`

3. 구현 현황

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 테이블)	로컬/서버 모두 등록 완료

3.2 미완료 / 검증 필요 항목

항목	상태	비고
채널 API 실제 호출 테스트	대기	카카오 채널 개설 후 가능
템플릿 조회 테스트	대기	템플릿 등록/검수 후 가능
알림톡 발송 테스트	대기	채널+템플릿 준비 후 가능
친구톡 발송 테스트	대기	채널 친구 추가 후 가능
SMS 대체발송 테스트	대기	바로빌 SMS 서비스 활성화 필요
대량 발송 테스트	대기	단건 테스트 완료 후
에러 핸들링 고도화	대기	실제 API 응답 확인 후 개선

4. API 메서드 목록

4.1 BarobillService 카카오톡 메서드

메서드	SOAP Action	설명
`getKakaotalkChannels`	`GetKakaotalkChannels`	채널 목록 조회
`getKakaotalkChannelManagementUrl`	`GetKakaotalkChannelManagementURL`	채널 관리 URL (바로빌 페이지)
`getKakaotalkTemplates`	`GetKakaotalkTemplates`	템플릿 목록 조회
`getKakaotalkTemplateManagementUrl`	`GetKakaotalkTemplateManagementURL`	템플릿 관리 URL
`sendATKakaotalk`	`SendATKakaotalk`	알림톡 단건 발송
`sendATKakaotalkEx`	`SendATKakaotalkEx`	알림톡 단건 발송 (버튼 포함)
`sendATKakaotalks`	`SendATKakaotalks`	알림톡 대량 발송
`sendFTKakaotalk`	`SendFTKakaotalk`	친구톡 텍스트 단건
`sendFTKakaotalks`	`SendFTKakaotalks`	친구톡 텍스트 대량
`sendFIKakaotalk`	`SendFIKakaotalk`	친구톡 이미지
`sendFWKakaotalk`	`SendFWKakaotalk`	친구톡 와이드 이미지
`getSendKakaotalk`	`GetSendKakaotalk`	전송 결과 단건 조회
`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 사전 준비 (비개발)

법인 명의 휴대폰으로 카카오톡 채널 개설
바로빌 관리자에서 카카오톡 서비스 신청
바로빌 채널 관리 URL에서 카카오 채널 연동
알림톡 템플릿 등록 및 카카오 검수 대기

7.2 개발 (채널 연동 후)

테스트 서버에서 GetKakaotalkChannels 호출 → 채널 목록 확인
GetKakaotalkTemplates 호출 → 템플릿 목록 확인
알림톡 테스트 발송 → 응답/상태 확인
친구톡 테스트 발송
에러 응답 코드 정리 및 핸들링 보강
SMS 대체발송 테스트
대량 발송 테스트 (수신자 다건)
운영 서버 전환 (testws → ws)

7.3 추후 고도화

발송 이력 DB 저장 (현재는 바로빌 API 조회만)
자동 발송 연동 (주문 확인, 배송 알림 등)
발송 통계 대시보드
엑셀 업로드 대량 발송
주소록(고객 DB) 연동

8. 활용 계획: 전자계약(E-Sign) 알림톡 연동

상세 구현 계획서: 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. 참고 자료

변경 이력

날짜	버전	변경 내용
2026-02-14	0.2	전자계약(E-Sign) 알림톡 연동 활용 계획 추가
2026-02-14	0.1	초안 작성 - 코드 구현 완료, 실 서비스 연동 대기

13 KiB Raw Blame History