Files
Gnuboard7/plugins/_bundled/sirsoft-message_bizppurio/docs/api/notification-bindings.md
T
chym1217 0a6a8d6968 fix(message_bizppurio): 결과코드 5002 언어팩 누락 + 알림톡 템플릿 저장 승인검증 부재 수정
PR 준비 최종 검토 중 문제코드 처리 대조표를 재검증하며 발견한 결함 2건.

- ResultCodeResolver 가 5002(요청 과다)를 재시도 대상으로 분류하지만 ko/en/ja
 언어팩 어디에도 사유가 없어 코드값만 노출되던 결함 수정
- 알림톡 템플릿 연결 저장이 승인 상태(RDY/ACT) 재검증 없이 그대로 upsert되어,
 화면 드롭다운(승인 템플릿만 노출)을 우회한 API 직접 호출 시 미승인 템플릿도
 저장 가능했던 결함 수정 — bind 에 카카오 승인 목록 대조 추가, 조회 자체
 실패 시에도 안전측으로 저장 거부
2026-07-28 16:56:13 +09:00

7.5 KiB

Notification Bindings API 레퍼런스

소유: plugin sirsoft-message_bizppurio · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.


TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Notification Bindings 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

GET /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings

  • 라우트명: api.plugins.sirsoft-message_bizppurio.admin.notification-bindings.index
  • 컨트롤러: Plugins\Sirsoft\MessageBizppurio\Controllers\Admin\NotificationBindingController@index
  • 인증/권한: auth:sanctum + permission:sirsoft-message_bizppurio.messaging.view

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
bindings array []

응답 예시

HTTP/1.1 200
{
    "success": true,
    "message": "messages.success",
    "data": {
        "bindings": []
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-message_bizppurio.messaging.view)이 없는 경우

설명

알림 설정 화면의 알림톡 탭이 소비하는 목록이다. 코어 알림 정의 중 채널에 alimtalk 을 포함하는 활성 알림 전체를, 연결된 알림톡 템플릿(binding)과 조인해 반환한다. 미연결 알림은 is_bound=false 이고 template_code/template_name 은 null, fallback_sms_enabled 는 false 다. variables 는 코어 알림 정의의 변수 목록으로, 편집 모달의 "제공 변수" 안내에 쓰인다.

POST /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings

  • 라우트명: api.plugins.sirsoft-message_bizppurio.admin.notification-bindings.store
  • 컨트롤러: Plugins\Sirsoft\MessageBizppurio\Controllers\Admin\NotificationBindingController@store
  • 인증/권한: auth:sanctum + permission:sirsoft-message_bizppurio.messaging.manage

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification_type body string 예 max 100
template_code body string 아니오 max 50
template_name body string 아니오 max 255 template 이름 (식별자)
fallback_sms_enabled body boolean 아니오 —

요청 예시

POST /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "notification_type": "예시값",
    "template_code": "예시값",
    "template_name": "예시 이름",
    "fallback_sms_enabled": true
}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
bindings object {"실측 예시값":{"notification_type":"실측 예시값","template_code":"…

응답 예시

HTTP/1.1 200
{
    "success": true,
    "message": "messages.binding.saved",
    "data": {
        "bindings": {
            "실측 예시값": {
                "notification_type": "실측 예시값",
                "template_code": "실측 예시값",
                "template_name": "실측 예시값",
                "fallback_sms_enabled": true
            }
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-message_bizppurio.messaging.manage)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
422 Unprocessable Entity template_code 가 카카오 승인 상태(RDY/ACT)가 아니거나, 카카오 승인 목록 조회 자체가 실패(자격증명 미설정·장애)한 경우 (error.kakao_message/error.result_code)

설명

알림에 알림톡 템플릿을 연결(생성/갱신)한다. 알림톡 탭 편집 모달의 [저장] 이 호출한다. (notification_type, alimtalk) 당 1개 연결이므로, 이미 연결이 있으면 갱신(upsert)된다. 저장은 코어 알림 설정 저장 버튼과 무관하게 이 API 로 직접 수행되어 코어 우회가 없다(§6-2). 저장 전 카카오 승인 상태(RDY/ACT)를 서버측에서 재검증하며, 미승인 코드거나 카카오 조회 자체가 실패하면 422 로 거부한다(편집 모달 드롭다운의 승인 템플릿 필터는 화면 단계일 뿐이라, 이를 우회한 직접 API 호출로 미승인 템플릿이 저장되는 것을 막기 위함). 연결 해제(template_code 빈 값)는 이 검증을 거치지 않는다.

GET /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings/approved-templates

  • 라우트명: api.plugins.sirsoft-message_bizppurio.admin.notification-bindings.approved-templates
  • 컨트롤러: Plugins\Sirsoft\MessageBizppurio\Controllers\Admin\NotificationBindingController@approvedTemplates
  • 인증/권한: auth:sanctum + permission:sirsoft-message_bizppurio.messaging.view

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/plugins/sirsoft-message_bizppurio/admin/notification-bindings/approved-templates HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-message_bizppurio.messaging.view)이 없는 경우

설명

연동 편집 모달의 "연결 템플릿" 드롭다운을 채우는 소스다. 카카오 템플릿 목록 중 serviceStatus 가 RDY(발송전)·ACT(정상)인 승인 템플릿만 반환한다. 자격증명(bizId·apiKey·senderKey) 미설정이거나 kapi 조회 실패 시 422 로 카카오 사유를 그대로 전달한다.