Gnuboard7/plugins/_bundled/sirsoft-message_bizppurio/README.md

Bizppurio Messaging Plugin for G7

비즈뿌리오(Bizppurio)를 연동해 문자(SMS/LMS)와 카카오 알림톡을 발송하는 G7 플러그인입니다.

G7 코어 알림 시스템에 문자·알림톡 채널을 추가해, 회원가입·주문 등 코어/모듈이 발화하는 알림을 문자와 알림톡으로도 자동 발송합니다. 발송 결과는 비즈뿌리오가 보내는 webhook 통보로 수신해 성공/실패와 실패 사유를 발송 이력에 기록합니다.

주요 기능 · 요구 사항 · 설치 · 관리자 설정 · webhook 등록 · 발송 흐름 · 알림톡 템플릿 연동 · 발송 결과 코드 · 훅 · API · 테스트

---

주요 기능

• 문자(SMS/LMS) 발송 — 본문 길이에 따라 SMS/LMS 자동 선택
• 카카오 알림톡 발송 — 승인된 템플릿의 본문·버튼·바로연결·강조표기·아이템리스트·대표링크까지 반영
• 알림톡 미승인/미연결 시 문자로 자동 대체발송(옵션)
• 회원·비회원 대상 알림에 문자 채널 연동 (비회원은 주문 시 입력한 연락처 사용)
• 비즈뿌리오 webhook 리포트 수신으로 발송 결과(성공/실패/사유) 자동 기록
• 검수(테스트) 모드 — 실제 발송 없이 화면·흐름 검증
• 지갑 잔액 부족·후불 한도 초과 시 관리자 알림 (반복 발송 방지 쿨다운 적용)
• 관리자 "알림 발송 이력" 화면에 문자·알림톡 결과 통합 표시
• 알림톡 템플릿 목록·상태·내용 조회 및 알림 연결 (템플릿 등록·검수는 비즈뿌리오 콘솔에서 진행)
• 알림톡 템플릿이 카카오에서 삭제·차단·승인취소된 경우 "사용 불가 — 재연결 필요" 표시

---

요구 사항

구분	항목	내용
플랫폼	G7	>= 7.0.3
플랫폼	PHP	^8.2
사전 준비	비즈뿌리오 계정	가입 + API 사용 승인
사전 준비	문자 발송	발신번호 사전 등록 (비즈뿌리오 콘솔)
사전 준비	알림톡 발송	카카오 발신프로필 등록 + 발송할 템플릿의 카카오 검수 승인

운영 모드로 전환하려면 비즈뿌리오 아이디·비밀번호·API 키·발신번호가 모두 입력되어야 하며, 이 시점부터 실제 발송과 비용이 발생합니다.

---

설치

플러그인을 G7 프로젝트의 플러그인 디렉토리에 배치합니다.

plugins/sirsoft-message_bizppurio

프론트엔드 에셋을 수정한 경우 플러그인 디렉토리에서 빌드합니다.

npm install
npm run build

그다음 G7 관리자에서 플러그인을 활성화합니다. 설치 시 회원 대상 알림의 문자·알림톡 채널 기본 템플릿(제목·본문·수신자)이 알림 설정에 자동으로 채워집니다.

---

관리자 설정

관리자 플러그인 설정 화면에서 비즈뿌리오 계정 정보를 입력합니다.

설정	필수 여부	설명
검수 모드	-	활성화 시 실제 발송 없이 검수용으로만 동작. 발송 이력에 "검수" 라벨로 표시되어 실제 장애와 구분됨
비즈뿌리오 아이디 / 비밀번호	운영 시 필수	비즈뿌리오 계정 로그인 정보
API 키	운영 시 필수	비즈뿌리오 API 인증에 사용
발신번호	운영 시 필수	문자 발송용 발신번호. 비즈뿌리오 콘솔에 사전 등록된 번호만 사용 가능
알림톡 발신프로필 키	알림톡 사용 시 필수	카카오 알림톡 발송에 사용할 발신프로필 키
잔액부족 알림 재발송 간격(초)	선택 (기본 3600)	잔액 부족/한도 초과 실패 시 관리자 알림의 최소 재발송 간격. 대량 실패 시 반복 발송 방지
알림톡 내용 캐시 시간(분)	선택 (기본 60)	카카오 템플릿 내용 재사용 시간. 0이면 매 발송마다 최신 조회, [캐시 초기화] 버튼으로 즉시 반영 가능

검수와 운영은 별도의 비즈뿌리오 계정으로 운영하는 것을 권장합니다. 비밀번호·API 키·발신프로필 키는 관리자 설정 화면에서만 입력하며 프론트엔드로 노출되지 않습니다.

---

webhook(발송 결과 리포트) 등록

비즈뿌리오가 발송 결과를 통보할 URL을 비즈뿌리오 콘솔에 등록해야 발송 결과(성공/실패/사유)가 발송 이력에 자동 기록됩니다.

이 등록을 하지 않으면 발송 자체는 되지만 성공/실패 여부를 확인할 수 없습니다.

https://your-domain.com/api/plugins/sirsoft-message_bizppurio/webhook

정확한 URL은 관리자 플러그인 설정 화면의 환경설정 탭에서도 복사할 수 있습니다.

---

발송 흐름

코어/모듈이 알림 발화 (예: 회원가입, 주문 완료)
→ 알림 설정에 연결된 문자·알림톡 채널로 발송 작업 큐잉
→ 알림톡: 카카오 승인 템플릿 사용, 미승인/미연결 시 문자로 대체발송(옵션)
→ 문자: 본문 길이에 따라 SMS/LMS 자동 선택
→ 비즈뿌리오 발송 API 호출
→ 비즈뿌리오가 webhook 으로 결과(성공/실패/사유) 통보
→ 발송 이력에 결과 기록, 실패 시 사유·결과코드 함께 기록

일시적 오류(카카오 시스템 오류, 처리 지연, 게이트웨이 오류 등)로 실패한 경우 자동으로 재시도합니다. 지갑 잔액 부족·후불 한도 초과는 재시도 대상이 아니며, 즉시 실패 처리와 함께 관리자에게 알림이 발송됩니다.

---

알림톡 템플릿 연동

카카오 알림톡 템플릿의 등록·수정·검수·상태변경은 비즈뿌리오 콘솔에서 진행합니다. 이 플러그인의 설정 화면(알림톡 템플릿 탭)은 콘솔에 등록된 템플릿의 목록·상태·내용을 조회하고, 발송가능(승인) 상태의 템플릿을 알림에 연결하는 역할만 담당합니다.

상태	발송 가능	설명
발송가능	✅	카카오 검수 승인 완료, 알림에 연결해 발송 가능
검수중	❌	카카오 검수 진행 중
반려	❌	카카오 검수 반려, 콘솔에서 재신청 필요
미검수	❌	콘솔에 등록만 되고 검수 신청 전 상태
중지	❌	사용 중지된 템플릿

알림에 연결한 템플릿이 이후 카카오에서 삭제·차단되거나 승인이 취소되면, 알림 설정 화면의 해당 알림에 "사용 불가 — 재연결 필요"가 표시됩니다. 이 경우 알림톡 템플릿 탭에서 다른 승인 템플릿으로 다시 연결해야 합니다.

---

발송 결과 코드

비즈뿌리오/카카오가 반환하는 결과 코드는 4가지로 분류되어 처리됩니다.

분류	처리 방침
성공	발송 완료
재시도 (일시 오류)	자동 재시도 대상 (예: 카카오 시스템 오류, 처리 지연, 게이트웨이 오류)
잔액 부족	즉시 실패 처리 + 관리자 자체 알림
영구 실패	즉시 실패 처리, 재시도하지 않음

주요 코드 예시:

코드	분류	사유
1000 4100 6600 7000	성공	발송/리포트 성공
9070	잔액 부족	잔액 부족(문자)
9071	잔액 부족	후불 한도 초과
7436	잔액 부족	지갑 잔액 부족(알림톡)
4400	영구 실패	음영 지역
7103	영구 실패	발신 프로필 키 무효

발송 이력 화면에는 사유 (코드) 형식(예: "음영 지역 (4400)")으로 표시됩니다. 전체 코드 목록은 lang/ko/result_codes.php / lang/en/result_codes.php에 정의되어 있으며, lang에 없는 코드는 코드만 표시됩니다.

---

가용 훅 (Hook)

다른 모듈이나 플러그인에서 아래 훅에 연결해 잔액부족 상황을 확장 처리할 수 있습니다.

액션 훅

훅 이름	시점	인수
sirsoft-message_bizppurio.balance.low	잔액 부족·한도 초과로 발송 실패 시 (쿨다운 내 최초 1회)	string $resultCode, string $channel

훅 등록 예시

use App\Extension\HookManager;

HookManager::addAction(
    'sirsoft-message_bizppurio.balance.low',
    function (string $resultCode, string $channel) {
        // 예: 잔액 부족 시 Slack으로도 별도 알림
        SlackNotifier::send("비즈뿌리오 잔액 부족: 채널={$channel}, 코드={$resultCode}");
    },
    priority: 10
);

$resultCode는 잔액 부족(9070 문자 / 7436 알림톡) 또는 후불 한도 초과(9071) 코드입니다. 이 훅은 관리자 자체 알림(잔액부족/후불한도초과 안내)을 발화하는 지점과 동일하며, 채널별 쿨다운(기본 3600초) 동안 한 번만 실행됩니다.

---

API

전체 엔드포인트 레퍼런스는 docs/api/README.md를 참고하세요.

문서	내용
webhook.md	비즈뿌리오 발송 결과 리포트 수신
templates.md	알림톡 템플릿 조회
alimtalk-templates.md	알림톡 템플릿 관리자 API
notification-bindings.md	알림-템플릿 연결
dispatch-results.md	발송 결과 조회
report.md	발송 결과 리포트 URL 조회

권한

권한	설명
sirsoft-message_bizppurio.messaging.view	발송 이력, 알림톡 템플릿, 발송 결과 조회
sirsoft-message_bizppurio.messaging.manage	알림톡 템플릿 연결, 캐시 초기화 등 관리 작업

---

삭제 시 동작

플러그인을 삭제하면 이 플러그인이 알림 설정에 추가했던 문자·알림톡 채널이 함께 정리됩니다. 메일·사이트 내 알림 등 다른 채널과 알림 자체는 그대로 유지되며, 플러그인을 다시 설치하면 문자·알림톡 채널이 자동으로 복원됩니다.

---

보안 및 운영 참고

• 비즈뿌리오 비밀번호, API 키, 알림톡 발신프로필 키는 외부에 노출하지 마세요. 관리자 설정 화면에서만 입력하며 프론트엔드로 노출되지 않습니다.
• 운영 모드 전환 전 검수 모드에서 문자·알림톡 발송 흐름을 먼저 확인하세요. 운영 모드는 실제 발송과 비용이 발생합니다.
• webhook URL을 비즈뿌리오 콘솔에 등록하지 않으면 발송 결과 확인이 불가능합니다.
• 검수와 운영은 별도의 비즈뿌리오 계정 사용을 권장합니다.
• 지갑 잔액/후불 한도를 주기적으로 확인하세요. 부족 시 관리자 알림이 발송되지만, 알림 자체도 같은 채널(문자/알림톡)을 사용하지 않는 별도 채널(예: 사이트 내 알림, 메일)로 함께 받는 것을 권장합니다.

---

테스트

플러그인을 G7 프로젝트에 배치한 뒤 G7 루트에서 PHP 테스트를 실행합니다.

php artisan test plugins/sirsoft-message_bizppurio/tests

프론트엔드 테스트와 빌드는 플러그인 디렉토리에서 실행합니다.

npm install
npm run test:run
npm run build

---

라이선스

MIT