[EP06] Sendon.io 카카오 알림톡 API 전체 연동 서비스 구현

[ImNM]

개요

기존 NCP 기반 알림톡 연동을 Sendon.io API v2로 전환하고, 알림톡 관련 전체 기능을 연동하는 서비스 레이어를 구현한다.

API Provider: Sendon.io
Base URL: https://api.sendon.io
인증: HTTP Basic Auth (Authorization: Basic base64(ID:APIKEY)) + IP 화이트리스트

관련 에픽: DuDoong-WorkBook/epics/EP06-알림톡-토큰-BM.md

---

연동 범위

1. 어드민용 — 테스트 발송 & 수기 발송

기존 서비스 자동 발송(주문완료/취소 등)은 이미 NCP 기반으로 구현되어 있으므로 이 이슈에서는 제외.
이 이슈에서는 어드민에서의 테스트 발송 및 수기 발송(공지사항 등) 기능을 구현한다.

API	메서드	엔드포인트	용도
알림톡 발송	POST	/v2/messages/kakao/alim-talk	테스트 발송, 공지사항 수기 발송
발송 그룹 조회	GET	/v2/messages/kakao/groups/{groupId}	발송 결과 확인
건별 결과 조회	GET	/v2/statistics/messaging/groups/{groupId}/messages	개별 수신 상태 확인
발송 취소	POST	/v2/messages/kakao/groups/{groupId}/cancel	예약 발송 취소
즉시 발송	POST	/v2/messages/kakao/groups/{groupId}/send	예약 → 즉시 전환

어드민 발송 시나리오:

• 테스트 발송: 템플릿 검수 전후 내부 번호로 테스트 메시지 발송 (변수 치환 확인용)
• 공지사항 발송: 이벤트 참가자/호스트 대상 일괄 공지 (예: 행사 변경, 긴급 안내)
• 예약 발송: 특정 시간에 발송 예약 + 필요 시 취소

2. 어드민용 — 채널(발신프로필) 관리

API	메서드	엔드포인트
채널 목록 조회	GET	/v2/messages/kakao/send-profiles
채널 상세 조회	GET	/v2/messages/kakao/send-profiles/{id}
채널 인증 요청	POST	.../send-profiles/request-auth-token
채널 등록	POST	.../send-profiles/register

3. 어드민용 — 템플릿 관리

API	메서드	엔드포인트
템플릿 생성	POST	.../send-profiles/{id}/templates
템플릿 목록 조회	GET	.../send-profiles/{id}/templates
템플릿 상세 조회	GET	.../send-profiles/{id}/templates/{tid}
템플릿 수정	POST	.../templates/{tid}/update
템플릿 삭제	POST	.../templates/{tid}/delete
검수 요청	POST	.../templates/{tid}/review
검수 취소	POST	.../templates/{tid}/review-cancel

템플릿 타입별 제약사항

메시지 타입 (templateMessageType):

타입	설명	글자수
BA	기본형	본문 1,000자
EX	부가정보형	본문 1,000자 + 부가정보 500자
AD	채널추가형	본문 1,000자 + 채널추가 안내 80자
MI	복합형	본문 1,000자 + 부가정보 500자 + 채널추가 80자

강조 타입 (templateEmphasizeType):

타입	필수 요소	제약
NONE	없음	-
TEXT	Title + Subtitle (둘 다 필수)	Title: Android 23자/iOS 27자, Subtitle: Android 18자/iOS 21자
IMAGE	이미지 URL	사전 업로드 필수
ITEM_LIST	아이템 리스트	상품/서비스 목록

버튼 규칙:

• 최대 5개, ordering으로 순서 지정
• 타입: WL(웹링크), AL(앱링크), BK(봇키워드), MD(메시지전달), DS(배송조회), AC(채널추가)
• WL: urlMobile, urlPc 필수
• AL: schemeAndroid, schemeIos 지원

변수 규칙:

• #{변수명} 형식 — 본문에서 사용, 발송 시 variables로 치환
• 부가정보(templateExtra)에서는 변수 사용 불가 — 고정 텍스트만

---

⚠️ 카카오 템플릿 검수 가이드

카카오 검수는 영업일 기준 1~3일 소요. 반려 시 수정 후 재검수 필요.

검수 상태값:

상태	설명
NEED_REVIEW	검수 전 (생성 직후)
IN_REVIEW	검수 진행 중
APPROVED	승인 완료 → 발송 가능
REJECTED	반려 → 수정 후 재검수
DORMANT	휴면 (장기 미사용)
DELETED	삭제됨

검수 통과를 위한 핵심 규칙:

1. 정보성 메시지만 허용 — 알림톡은 사용자가 요청/동의한 정보 전달 목적만 가능

   • ✅ 주문확인, 배송안내, 예매완료, 일정변경, 결제내역
   • ❌ 할인 프로모션, 이벤트 홍보, 재구매 유도 → 광고성은 친구톡 사용

2. 변수(#{...})에 광고/홍보 문구 삽입 금지 — 검수 시 변수 자리에 어떤 값이 들어가는지도 심사 대상

3. 발신자 정보 명시 — 누가 보내는 메시지인지 명확해야 함

4. URL은 실제 서비스와 관련된 것만 — 외부 광고 링크, 리다이렉트 URL 금지

5. 불법/부적절한 내용 금지 — 도박, 성인, 불법 금융 등

6. 템플릿 내용과 실제 발송 내용 일치 — 변수 치환 후 결과가 템플릿 의도와 달라지면 안 됨

7. 부가정보(EX/MI 타입) — 고객센터, 운영시간 등 고정 안내 정보만 가능, 변수 불가

반려 빈출 패턴:

• 본문에 "할인", "특가", "이벤트 참여" 등 광고성 표현 포함
• 변수에 마케팅 메시지가 들어갈 수 있는 구조
• 버튼 URL이 프로모션/랜딩 페이지로 연결
• 발신 주체가 불명확한 템플릿
• 수신자가 요청하지 않은 정보를 전달하는 구조

DuDoong에서의 적용:

• 공지사항 발송 시 → "공연 일정 변경 안내", "행사 장소 변경" 등 정보성으로 작성
• 호스트 공지 → "#{공연명} 일정이 변경되었습니다" 식의 사실 전달
• 마케팅/재방문 유도는 알림톡이 아닌 친구톡(FriendTalk) 별도 검토 필요

---

4. 어드민용 — 이미지 업로드

API	메서드	엔드포인트
알림톡 이미지 업로드	POST	/v2/messages/kakao/alimtalk/image
대체문자 이미지 업로드	POST	/v2/messages/kakao/fallback/image

• 알림톡 이미지: 최대 5MB, 최대 3개 (JPG/PNG/GIF/BMP/TIFF)
• 대체문자 이미지: 최대 300KB

5. 어드민용 — 수신거부 관리

API	메서드	엔드포인트
수신거부 추가	POST	/v2/contacts/blocklist
수신거부 목록 조회	GET	/v2/contacts/blocklist
수신거부 삭제	POST	/v2/contacts/blocklist/{id}/delete

6. 어드민용 — 포인트/충전금액 조회 및 단가 관리

API	메서드	엔드포인트
포인트 잔액/내역 조회	GET	/v2/point/points
서비스 단가 조회	GET	/v2/point/costs
결제 내역 조회	GET	/v2/payment/payment-histories
발신번호 목록 조회	GET	/v2/sender/numbers

어드민 대시보드에서 Sendon 계정 잔액, 충전 내역, 메시지 단가(AT/AI/AE/FT 등) 확인 가능하도록 구현

---

구현 태스크

• Sendon API Client 모듈 — Feign 또는 WebClient 기반, Basic Auth 설정
• 공통 응답 핸들링 — HTTP 200 고정 + body code 필드 기반 성공/실패 판단
• [어드민] 테스트 발송 서비스 — 내부 번호로 템플릿 테스트 발송, 변수 치환 미리보기
• [어드민] 수기 발송 서비스 — 공지사항 등 대상자 지정 일괄 발송 + 예약 발송/취소
• [어드민] 발송 결과 조회 — 그룹별/건별 발송 상태 확인
• [어드민] 채널 관리 서비스 — 조회, 등록, 인증
• [어드민] 템플릿 관리 서비스 — CRUD + 검수 요청/취소 + 검수 상태 모니터링
• [어드민] 이미지 업로드 서비스 — multipart/form-data 처리
• [어드민] 수신거부 관리 서비스 — 추가, 조회, 삭제
• [어드민] 포인트/단가 조회 서비스 — 잔액, 충전 내역, 메시지 단가
• 설정 분리 — application.yml에 Sendon API Key, ID, Base URL 프로파일별 관리

API 특이사항

• 모든 HTTP 응답 코드가 200 — body의 code 필드로 실제 결과 판단 필요
• 수정/삭제가 PUT/DELETE 대신 POST /{id}/update, POST /{id}/delete 패턴
• 커서 기반 페이징 (cursor + limit)
• Rate limit 구체 수치 미공개 (429 발생 시 감소 필요, 지원팀 문의)
• 템플릿 검수 소요: 영업일 1~3일