Files
Gnuboard7/plugins/_bundled/sirsoft-message_bizppurio/docs/api/dispatch-results.md
T
chym1217 11f1d79540 feat(message_bizppurio): 코어 알림 발송 이력 화면에 문자·알림톡 결과 주입
발송 결과(성공/실패·사유·잔액부족·SMS 대체발송)를 코어 "알림 발송 이력" 화면의 각 행에
표시한다. 코어 앱·코어 테이블 무수정 — 연결 표식은 bizppurio_dispatches.notification_log_id
에만 두고, 발송 사이클의 코어 after_log_sent/after_log_failed 훅으로 그 로그 id 를 연결한다.

- 결과 조회는 파라미터 없는 GET /dispatch-results/recent 로 최근 결과 맵을 받아 row.id 매칭
 (목록 로드 순서에 무관 — 빈 배열 전송·타이밍으로 결과가 비던 문제 해소).
- 코어 이력 datagrid 에 결과 컬럼을 layout_extensions 로 주입하고, 행 토글에도 상세 결과를
 얹는다. 메일·사이트내알림 탭에선 컬럼(헤더 포함)을 숨긴다. 다크모드 배지 색 보강.
- 브라우저 검수용 데모 시더(4상태·엣지 케이스 21건) + 전 계층 테스트(백엔드·Vitest 렌더)
 + 시나리오 매니페스트 + API 레퍼런스 동반.
2026-07-28 12:36:26 +09:00

11 KiB

Dispatch Results API 레퍼런스

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


TL;DR (5초 요약)

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

POST /api/plugins/sirsoft-message_bizppurio/admin/dispatch-results/lookup

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

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification_log_ids body array 아니오 max 100 notification log 식별자 배열

요청 예시

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

{
    "notification_log_ids": [
        "예시값"
    ]
}

응답 필드 (data 내부)

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

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

응답 예시

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

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-message_bizppurio.messaging.view)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

코어 "알림 발송 이력" 화면에 얹은 결과 컬럼(layout_extensions overlay)이 소비하는 조회 API 다. 현재 페이지에 표시된 코어 알림 로그 id 배열(notification_log_ids, 최대 100)을 넘기면, 그 로그에 연결된 비즈뿌리오 발송 결과를 로그 id 를 키로 하는 맵으로 한 번에 돌려준다(행마다 개별 호출하지 않아 N+1 을 피한다). 코어 알림 로그 테이블은 수정하지 않으며, 연결 표식은 비즈뿌리오 쪽 (bizppurio_dispatches.notification_log_id)에만 둔다.

매칭되지 않는 로그 id(메일·사이트내알림 등 비-비즈뿌리오 발송)는 결과 맵에서 제외된다 — 화면에서는 그 행의 결과 컬럼이 빈 셀이 된다. 결과에는 전화번호 등 민감정보를 포함하지 않는다(결과 컬럼은 상태· 사유만 표시).

응답 필드 (data.results — 키는 notification_log_id, 값은 결과 객체)

필드 타입 용도
status string|null 발송 상태: sent / success / failed (DispatchStatus)
status_label string|null 로케일 상태 라벨 (예: "성공", "실패", "발송중")
result_code string|null 결과 코드 (발송응답 또는 webhook 리포트). 리포트 미수신 시 null
result_label string|null 사유 (코드) 표시 라벨 (예: "음영 지역 (4400)"). 코드 없으면 null
is_low_balance boolean 잔액 부족(9070 문자 / 7436 알림톡) 여부
fallback_status string|null SMS 대체발송 결과 (webhook TELRES). 없으면 null
channel string|null 발송 채널: sms / lms / alimtalk

응답 예시

{
    "success": true,
    "message": "성공",
    "data": {
        "results": {
            "128": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "4400",
                "result_label": "음영 지역 (4400)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            }
        }
    }
}

GET /api/plugins/sirsoft-message_bizppurio/admin/dispatch-results/recent

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

요청 파라미터

요청 파라미터 없음.

요청 예시

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

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
results object {"21":{"status":"pending","status_label":"대기","result_cod…

응답 예시

HTTP/1.1 200
{
    "success": true,
    "message": "messages.success",
    "data": {
        "results": {
            "21": {
                "status": "pending",
                "status_label": "대기",
                "result_code": null,
                "result_label": null,
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "alimtalk"
            },
            "20": {
                "status": "success",
                "status_label": "성공",
                "result_code": "7000",
                "result_label": "성공 (7000)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "alimtalk"
            },
            "19": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "7206",
                "result_label": "검수되지 않은 템플릿 (7206)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "alimtalk"
            },
            "18": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "7436",
                "result_label": "지갑 잔액 부족(알림톡) (7436)",
                "is_low_balance": true,
                "fallback_status": "실패",
                "channel": "alimtalk"
            },
            "17": {
                "status": "success",
                "status_label": "성공",
                "result_code": "7000",
                "result_label": "성공 (7000)",
                "is_low_balance": false,
                "fallback_status": "성공",
                "channel": "alimtalk"
            },
            "16": {
                "status": "success",
                "status_label": "성공",
                "result_code": "7000",
                "result_label": "성공 (7000)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "alimtalk"
            },
            "15": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "6603",
                "result_label": "음영 지역 (6603)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "lms"
            },
            "14": {
                "status": "success",
                "status_label": "성공",
                "result_code": "6600",
                "result_label": "성공 (6600)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "lms"
            },
            "13": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "9999",
                "result_label": "9999",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "12": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "9070",
                "result_label": "잔액 부족(문자) (9070)",
                "is_low_balance": true,
                "fallback_status": null,
                "channel": "sms"
            },
            "11": {
                "status": "success",
                "status_label": "성공",
                "result_code": "4100",
                "result_label": "성공 (4100)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "10": {
                "status": "pending",
                "status_label": "대기",
                "result_code": null,
                "result_label": null,
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "9": {
                "status": "sent",
                "status_label": "발송중",
                "result_code": null,
                "result_label": null,
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "8": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "4410",
                "result_label": "잘못된 번호 (4410)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "7": {
                "status": "failed",
                "status_label": "실패",
                "result_code": "4400",
                "result_label": "음영 지역 (4400)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            },
            "6": {
                "status": "success",
                "status_label": "성공",
                "result_code": "4100",
                "result_label": "성공 (4100)",
                "is_low_balance": false,
                "fallback_status": null,
                "channel": "sms"
            }
        }
    }
}

에러 응답

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

설명