문자·알림톡 발송 결과를 DB에 기록하고, 비즈뿌리오 webhook(URL PUSH)으로 도달 여부를 갱신한다. 결과코드를 사유+분류로 해석하고, 잔액 부족 시 관리자에게 쿨다운(기본 1시간) 내 1회만 알린다. 발송 결과를 확인하는 화면은 플러그인 독립 페이지 대신 코어 알림 이력에 얹는 방식(후속)으로 이관하기로 하여, 이번에 만든 독립 이력 화면과 화면 전용 백엔드는 제거했다. webhook 결과 저장·수신·해석 뼈대는 유지한다.
3.8 KiB
3.8 KiB
Webhook API 레퍼런스
소유: plugin
sirsoft-message_bizppurio· 생성:php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Webhook 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
POST /api/plugins/sirsoft-message_bizppurio/webhook
- 라우트명:
api.plugins.sirsoft-message_bizppurio.webhook - 컨트롤러:
Plugins\Sirsoft\MessageBizppurio\Controllers\BizppurioWebhookController@handle - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| DEVICE | body | string | 아니오 | max 20 | |
| CMSGID | body | string | 아니오 | max 64 | |
| MSGID | body | string | 아니오 | max 64 | |
| PHONE | body | string | 아니오 | max 20 | |
| MEDIA | body | string | 아니오 | max 10 | |
| RESULT | body | string | 예 | max 10 | |
| REFKEY | body | string | 예 | max 32 | |
| TELRES | body | string | 아니오 | max 10 | |
| KAORES | body | string | 아니오 | max 10 |
요청 예시
POST /api/plugins/sirsoft-message_bizppurio/webhook HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json
{
"DEVICE": "예시값",
"CMSGID": "예시값",
"MSGID": "예시값",
"PHONE": "010-1234-5678",
"MEDIA": "예시값",
"RESULT": "예시값",
"REFKEY": "예시값",
"TELRES": "예시값",
"KAORES": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명
비즈뿌리오가 문자·알림톡 발송 결과를 URL PUSH 로 통보하는 리포트 수신 엔드포인트다. 운영자가 이 주소를 비즈뿌리오에 등록하면(환경설정 화면의 리포트 수신 주소), 발송 후 결과가 이 엔드포인트로 전송된다.
- 인증: 코어 토큰/IDV 미들웨어를 라우트 레벨에서 제외하고, 인증을 IP 화이트리스트로 대체한다. 화이트리스트 밖 IP 는 403.
- 처리:
REFKEY로 발송 이력을 조회한다. 없으면(위조/미매칭) 200 으로 흡수한다. 이미 리포트가 반영된 이력(reported_at존재)이면 replay 로 판정해 멱등 처리한다. 그 외에는RESULT코드를 분류(성공/실패/잔액부족)해 상태를 전이하고media·fallback_status·raw_payload·reported_at을 기록한다. - 잔액부족:
RESULT가 9070(문자)/7436(알림톡)이면 이력을 실패로 뒤집고 관리자에게 자체 알림을 1회 발송한다. - 응답은 항상 200 이다(비즈뿌리오가 실패 응답을 재전송하지 않도록). replay 멱등이 중복 처리를 막는다.