API 가이드 | PushHub

환경 설정

PushHub를 사용하기 위해서는 먼저 도메인 인증과 기본 설정이 필요합니다.
아래 단계를 따라 순차적으로 설정을 진행해 주세요.

1단계. 프로젝트 정보 설정

PushHub에서 프로젝트를 생성한 후, 도메인과 푸시 아이콘을 등록합니다.

웹사이트 도메인: 푸시 알림을 사용할 사이트 주소 (예: https://yourdomain.com)
푸시 아이콘 이미지: 푸시 알림에 표시될 아이콘
권장: PNG, 정사각형, 128×128 이상

2단계. 도메인 인증

도메인 소유 인증을 위해 아래의 HTML 파일을 다운로드하고, 해당 도메인의 루트 경로에 업로드해야 합니다.

예: https://yourdomain.com/pushhub-verification.html

3단계. 서비스 워커 & SDK 설정

푸시 알림을 수신하려면 아래 파일들을 반드시 업로드해야 합니다.

① Firebase Service Worker

firebase-messaging-sw.js 파일을 도메인 루트 경로에 업로드하세요.

📄 Service Worker 다운로드

예: https://yourdomain.com/firebase-messaging-sw.js

② PushHub SDK 추가

PushHub SDK CDN 및 init 코드 추가

<script src="https://pushhub.co.kr/pushhub_sdk.js"></script>
<script>
PushHub.init({
    apiKey: "YOUR_API_KEY",            // 프로젝트 API 키
    projectId: "YOUR_PROJECT_ID",      // 프로젝트 ID
    userId: "YOUR_SITE_USER_ID",       // 로그인 사용자 ID (푸시 수신자 기준)
    phone: "",                         // 사용자 전화번호 (선택)
    memo: ""                           // 사용자 메모 (선택)
});
</script>

※ 모든 페이지에 적용되어야 사용자 구독이 원활하게 처리됩니다.

권한 프롬프트 설정

사용자가 알림 권한을 허용할 수 있도록 표시되는 프롬프트 UI를 설정합니다.
PushHub는 기본적으로 3가지 유형의 프롬프트를 지원합니다.

슬라이드 프롬프트

화면 하단에서 슬라이드로 등장하는 기본 안내 형태입니다.

버튼 1/2 텍스트 입력 가능
표시 시간 설정 가능 (초 단위)

구독 벨

종 모양 아이콘이 고정되어 클릭 시 권한 요청을 유도합니다.

아이콘 위치, 색상 커스터마이징
토글 텍스트 표시 여부 설정 가능

사용자 정의 링크

개발자가 직접 디자인한 버튼/링크 클릭 시 권한을 요청합니다.

텍스트 및 배경색 자유 설정
설명 메시지 포함 가능

PushHub init 코드 예시

아래 코드를 참고하여 프로젝트에 맞는 프롬프트 타입을 설정하세요.

권한 프롬프트 설정 코드 추가

프롬프트 미리보기

아래 스타일을 참고하여 프로젝트에 맞는 프롬프트 타입을 설정하세요.

알림을 받고 싶다면 알림 설정을 수락해주세요

📢 사용자가 직접 권한 초기화하는 방법

Chrome: 주소창 왼쪽 자물쇠 아이콘 → "사이트 설정" → 알림 권한 "허용/차단/초기화"
Firefox: 주소창 옆 아이콘 클릭 → 권한 → "알림" 항목 초기화
Safari: 환경설정 → 웹사이트 탭 → 알림 → 해당 도메인 삭제

환영 알림 설정

사용자가 알림 권한을 허용한 직후 자동으로 푸시 알림을 발송할 수 있습니다.
이 알림은 구독 확인 메시지 또는 앱/서비스 소개 메시지로 활용할 수 있습니다.

enabled: 구독 직후 환영 알림을 보낼지 여부 (boolean)
title: 푸시 제목
message: 푸시 메시지 내용
clickLinkUrl: 클릭 시 이동할 URL (선택)
openInNewTab: 새 탭으로 열지 여부 (boolean)

⚠️ 주의: 환영 알림은 권한 허용 직후 1회만 자동 발송되며, 푸시 서버 연동이 정상이어야 작동합니다.

API 인증

BASE URL

https://api.pushhub.co.kr

PushHub API는 API Key 기반 인증을 사용합니다.
모든 요청에는 아래와 같은 방식으로 Authorization 헤더를 포함해야 합니다.

요청 헤더

Authorization: Bearer YOUR_API_KEY

발급된 API 키는 PushHub 관리자 페이지 > API 키 관리 메뉴에서 확인 가능합니다.

토큰 등록 및 갱신

이 API는 사용자가 알림 수신을 허용할 때 자동으로 호출되며, 디바이스 정보를 등록하거나 기존 토큰을 갱신합니다.
신규 등록된 디바이스에는 설정된 환영 메시지가 자동 발송될 수 있습니다.
※ 별도로 수동 호출하거나 수정할 수 없습니다.

주의: PushHub.init() 내 설정을 기반으로 동작합니다.

필수 파라미터: apiKey, projectId, userId

해당 값이 누락되거나 잘못 설정되면 토큰 등록이 정상적으로 동작하지 않습니다.

에러 응답 설명

400 Bad Request

token, projectId, apiKey 중 하나라도 누락된 경우

{"error": "필수 파라미터가 누락되었습니다."}

403 Forbidden

API Key가 유효하지 않거나, 프로젝트 도메인 인증이 완료되지 않은 경우

{"error": "API Key 인증 실패"}
{"error": "도메인 인증이 완료되지 않았습니다."}

응답 예시

{
    "success": true,
    "message": "신규 디바이스 토큰이 등록 되었습니다.",
    "token": "abc123tokenvalue"
}

{
    "success": true,
    "message": "디바이스 토큰이 갱신 되었습니다.",
    "token": "abc123tokenvalue"
}

{
    "success": true,
    "message": "등록된 토큰입니다."
}

토큰 전체 삭제

특정 사용자(user_id)에 등록된 모든 디바이스 토큰을 삭제합니다.
일반적으로 사용자가 알림 수신을 철회하거나, 모든 디바이스 연결을 해제할 때 사용됩니다.

요청 방식: DELETE

엔드포인트: /tokens/<user_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 user_id: 토큰을 삭제할 대상 사용자 ID (string)

에러 응답 설명

400 Bad Request

요청 시 user_id가 제공되지 않은 경우.

{"success": false, "error": "user_id는 필수입니다."}

404 Not Found

해당 user_id에 연결된 삭제할 토큰이 존재하지 않는 경우.

{"success": false, "error": "삭제할 토큰이 없습니다."}

500 Internal Server Error

DB 오류 또는 예기치 못한 예외가 발생한 경우.

{"success": false, "error": "삭제 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "message": "test_user에 해당하는 모든 토큰이 삭제되었습니다."
}

특정 토큰 삭제

특정 사용자(user_id)의 디바이스 중 하나의 token을 선택하여 삭제합니다.
알림 수신 해제를 개별 디바이스 단위로 처리하거나, 수동 제거 시 사용됩니다.

요청 방식: DELETE

엔드포인트: /tokens/<user_id>/<token>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 user_id: 토큰을 삭제할 대상 사용자 ID (string)
필수 token: 삭제할 디바이스 토큰 값 (string)

에러 응답 설명

400 Bad Request

user_id 또는 token이 누락된 경우.

{"success": false, "error": "user_id와 token은 필수입니다."}

404 Not Found

해당 user_id 및 token 조합이 존재하지 않거나 이미 삭제된 경우.

{"success": false, "error": "일치하는 토큰이 없거나 이미 삭제되었습니다."}

500 Internal Server Error

DB 오류 또는 예기치 못한 예외가 발생한 경우.

{"success": false, "error": "삭제 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "message": "지정된 토큰이 삭제되었습니다."
}

토큰 목록 조회

특정 사용자(user_id)에 등록된 모든 디바이스 토큰 정보를 조회합니다.
이 정보는 개별 푸시 발송 대상 필터링 등에 활용됩니다.

요청 방식: GET

엔드포인트: /tokens/<user_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 user_id: 토큰을 조회할 대상 사용자 ID (string)

에러 응답 설명

400 Bad Request

요청 시 user_id가 제공되지 않은 경우.

{"success": false, "error": "user_id는 필수입니다."}

404 Not Found

해당 user_id에 연결된 토큰이 존재하지 않는 경우.

{"success": false, "error": "등록된 토큰이 없습니다."}

500 Internal Server Error

DB 접속 오류 또는 예기치 못한 예외가 발생한 경우.

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "devices": [
        {
            "browser": "Chrome",
            "created_at": "2025-04-16 17:27",
            "device_id": 317,
            "device_info": "Chrome on Windows",
            "ip_address": "192.168.0.1",
            "is_subscribed": 1,
            "last_active_at": "2025-04-16 18:50",
            "platform": "web",
            "token": "abc123...",
            "token_updated_at": "2025-04-16 18:50"
        }
    ]
}

사용자 등록

새 사용자를 프로젝트에 등록합니다. user_id는 고유해야 하며, 이미 존재하는 경우 오류가 반환됩니다.

요청 방식: POST

엔드포인트: /users/create

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 user_id: 사용자 ID (고유값)
선택 phone: 사용자 전화번호
선택 memo: 사용자 메모

에러 응답 설명

400 Bad Request

user_id가 누락되었거나, 이미 존재하는 경우

{"success": false, "error": "user_id는 필수입니다."}
{"success": false, "error": "이미 존재하는 사용자 ID입니다."}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "등록 중 오류 발생: ..."}

요청 예시

{
    "user_id": "test123",
    "phone": "010-1234-1234",
    "memo": "VIP 고객님"
}

응답 예시

{
    "success": true,
    "message": "사용자 정보가 등록되었습니다.",
    'project_user_id': 101,
    "user": {
        "memo": "VIP 고객님",
        "phone": "010-1234-1234",
        "user_id": "test123"
    }
}

사용자 수정

기존 사용자의 전화번호 또는 메모 정보를 수정합니다.
project_user_id를 기준으로 수정되며, 존재하지 않는 사용자인 경우 404 에러가 반환됩니다.

요청 방식: POST

엔드포인트: /users/update

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 project_user_id: 수정 대상 사용자 ID (고유값)
선택 phone: 전화번호
선택 memo: 메모

에러 응답 설명

400 Bad Request

project_user_id가 누락된 경우

{"success": false, "error": "project_user_id는 필수입니다."}

404 Not Found

수정 대상 사용자가 존재하지 않을 경우

{"success": false, "error": "해당 사용자를 찾을 수 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류

{"success": false, "error": "수정 중 오류 발생: ..."}

요청 예시

{
    "project_user_id": 101,
    "phone": "010-1234-1234",
    "memo": "VIP 고객님"
}

응답 예시

{
    "success": true,
    "message": "사용자 정보가 수정되었습니다."
    'project_user_id': 101,
    "user": {
        "memo": "VIP 고객님",
        "phone": "010-1234-1234"
    }
}

사용자 삭제

지정한 project_user_id에 해당하는 사용자를 삭제합니다.
해당 사용자와 연결된 모든 디바이스 정보도 함께 제거됩니다.

요청 방식: DELETE

엔드포인트: /users/delete/<project_user_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 project_user_id: 삭제 대상 사용자 ID (고유값)

에러 응답 설명

400 Bad Request

필수값 project_user_id가 누락된 경우

{"success": false, "error": "project_user_id는 필수입니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류 발생 시

{"success": false, "error": "삭제 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "message": "사용자 정보가 삭제되었습니다."
}

사용자 상세 조회

지정된 project_user_id에 해당하는 사용자 정보를 조회합니다.
사용자 ID, 전화번호, 메모 등을 반환합니다.

요청 방식: GET

엔드포인트: /users/get/<project_user_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 project_user_id: 삭제 대상 사용자 ID (고유값)

에러 응답 설명

400 Bad Request

필수값 project_user_id가 누락된 경우

{"success": false, "error": "project_user_id는 필수입니다."}

404 Not Found

해당 사용자가 존재하지 않는 경우

{"success": false, "error": "사용자를 찾을 수 없습니다."}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "created_at": "2025-04-18 10:26",
    "memo": "VIP 고객",
    "phone": "010-1234-5678",
    "project_user_id": 387,
    "success": true,
    "updated_at": "2025-04-18 10:26",
    "user_id": "john123"
}

사용자 목록 조회

프로젝트에 등록된 사용자 목록을 조회합니다. 검색 필터를 통해 ID 또는 전화번호로 조회가 가능합니다.
결과는 페이징 처리가 되어 있으며, 각 사용자의 디바이스 등록 수 및 플랫폼 정보도 함께 반환됩니다.

요청 방식: GET

엔드포인트: /users/list

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

선택 search_type: 검색 기준 (user_id 또는 phone)
선택 keyword: 검색어
선택 page: 페이지 번호 (기본값: 1)

에러 응답 설명

400 Bad Request

잘못된 페이지 번호 등 유효하지 않은 입력값이 전달된 경우

{"success": false, "error": "유효한 page 값을 입력하세요 (1 이상의 정수)."}

404 Not Found

해당 사용자가 존재하지 않는 경우

{"success": false, "error": "조회된 사용자가 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류 발생 시

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 2,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "users": [
        {
            "project_user_id": 101,
            "user_id": "john123",
            "phone": "010-1234-5678",
            "memo": "VIP 고객",
            "created_at": "2025-04-01 10:00",
            "updated_at": "2025-04-10 16:00",
            "device_count": 2,
            "platforms": "web,android"
        }
    ]
}

그룹 등록 StarterBiz

새 그룹을 프로젝트에 등록합니다. group_name은 고유해야 하며, 동일한 이름이 이미 존재할 경우 오류가 반환됩니다.

요청 방식: POST

엔드포인트: /groups/create

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 group_name: 그룹 이름 (고유값)
선택 memo: 그룹 메모

에러 응답 설명

400 Bad Request

group_name이 누락되었거나, 이미 존재하는 경우

{"success": false, "error": "group_name은 필수입니다."}
{"success": false, "error": "이미 존재하는 그룹 이름입니다."}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "등록 중 오류 발생: ..."}

요청 예시

{
    "group_name": "VIP 고객",
    "memo": "광고 반응률 높은 사용자 그룹"
}

응답 예시

{
    "success": true,
    "message": "그룹 정보가 등록되었습니다.",
    "group_id": 102,
    "group": {
        "group_name": "VIP 고객",
        "memo": "광고 반응률 높은 사용자 그룹"
    }
}

그룹 수정 StarterBiz

기존 그룹의 이름 또는 메모 정보를 수정합니다.
group_id를 기준으로 수정되며, 존재하지 않는 그룹인 경우 404 에러가 반환됩니다.

요청 방식: POST

엔드포인트: /groups/update

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 group_id: 수정 대상 그룹 ID (고유값)
필수 group_name: 그룹 이름
선택 memo: 그룹에 대한 메모

에러 응답 설명

400 Bad Request

group_id 또는 group_name이 누락된 경우

{"success": false, "error": "group_id, group_name은 필수입니다."}

404 Not Found

수정 대상 그룹이 존재하지 않을 경우

{"success": false, "error": "해당 그룹을 찾을 수 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류

{"success": false, "error": "수정 중 오류 발생: ..."}

요청 예시

{
    "group_id": 102,
    "group_name": "VIP 고객",
    "memo": "광고 반응률 높은 사용자 그룹"
}

응답 예시

{
    "success": true,
    "message": "그룹 정보가 수정되었습니다.",
    "group_id": 102,
    "group": {
        "group_name": "VIP 고객",
        "memo": "광고 반응률 높은 사용자 그룹"
    }
}

그룹 삭제 StarterBiz

지정한 group_id에 해당하는 그룹을 삭제합니다.
해당 그룹에 포함된 사용자 연결 정보도 함께 제거됩니다.

요청 방식: DELETE

엔드포인트: /groups/delete/<group_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 group_id: 삭제 대상 그룹 ID (고유값)

에러 응답 설명

400 Bad Request

필수값 group_id가 누락된 경우

{"success": false, "error": "group_id는 필수입니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류 발생 시

{"success": false, "error": "삭제 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "message": "123 그룹이 삭제되었습니다."
}

그룹 상세 조회 StarterBiz

지정된 group_id에 해당하는 그룹 정보를 조회합니다.
그룹 이름 및 메모 등의 정보를 반환합니다.

요청 방식: GET

엔드포인트: /groups/get/<group_id>

인증 필요: Authorization 헤더 (API Key)

경로 파라미터

필수 group_id: 조회할 그룹의 고유 ID (고유값)

에러 응답 설명

400 Bad Request

필수값 group_id가 누락된 경우

{"success": false, "error": "group_id는 필수입니다."}

404 Not Found

해당 그룹이 존재하지 않는 경우

{"success": false, "error": "그룹을 찾을 수 없습니다."}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "group_id": 10,
    "group_name": "VIP 고객",
    "memo": "자주 이용하는 고객 그룹",
    "created_at": "2025-04-01 10:00",
    "updated_at": "2025-04-10 16:00"
}

그룹 목록 조회 StarterBiz

프로젝트에 등록된 그룹 목록을 조회합니다. 검색 필터를 통해 그룹명, 메모, 사용자 ID 또는 전화번호로 필터링이 가능합니다.
결과는 페이징 처리되며, 각 그룹의 사용자 수 정보도 함께 반환됩니다.

요청 방식: GET

엔드포인트: /groups/list

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

선택 search_type: 검색 기준 (group_name, memo, user_id, phone)
선택 keyword: 검색어
선택 page: 페이지 번호 (기본값: 1)

에러 응답 설명

400 Bad Request

유효하지 않은 페이지 번호 등 잘못된 요청인 경우

{"success": false, "error": "유효한 page 값을 입력하세요 (1 이상의 정수)."}

404 Not Found

조회 조건에 맞는 그룹이 없는 경우

{"success": false, "error": "조회된 그룹이 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 2,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "groups": [
        {
            "group_id": 10,
            "group_name": "VIP 고객",
            "memo": "자주 이용하는 고객 그룹",
            "created_at": "2025-04-01 10:00",
            "updated_at": "2025-04-10 16:00",
            "user_count": 5
        },
        {
            "group_id": 11,
            "group_name": "내부 테스트",
            "memo": "테스트용 그룹",
            "created_at": "2025-04-05 09:45",
            "updated_at": "2025-04-10 16:00",
            "user_count": 2
        }
    ]
}

그룹 사용자 등록 StarterBiz

선택한 그룹에 사용자를 등록합니다. 이미 등록된 사용자는 무시되며, 오류 없이 무시 처리됩니다.

요청 방식: POST

엔드포인트: /group/users/create

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 group_id: 등록할 그룹 ID
필수 project_user_ids: 등록할 사용자 ID 배열 ([101, 102, ...])

에러 응답 설명

400 Bad Request

필수값이 누락되었거나 유효하지 않은 경우

{"success": false, "error": "group_id와 project_user_ids는 필수입니다."}

404 Not Found

일치하는 사용자가 없는 경우

{"success": false, "error": "존재하지 않는 사용자 ID: [311]"}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "등록 중 오류 발생: ..."}

요청 예시

{
    "group_id": 102,
    "project_user_ids": [101, 102, 103]
}

응답 예시

{
    "success": true,
    "message": "사용자가 그룹에 등록되었습니다."
}

그룹 사용자 삭제 StarterBiz

지정한 group_id와 사용자 ID 배열에 해당하는 사용자들을 그룹에서 제거합니다.

요청 방식: POST

엔드포인트: /group/users/delete

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 group_id: 대상 그룹 ID
필수 project_user_ids: 삭제할 사용자 ID 배열 ([101, 102, ...])

에러 응답 설명

400 Bad Request

필수값이 누락되었거나 유효하지 않은 경우

{"success": false, "error": "group_id와 project_user_ids는 필수입니다."}

500 Internal Server Error

서버 처리 중 예외가 발생한 경우

{"success": false, "error": "삭제 중 오류 발생: ..."}

요청 예시

{
    "group_id": 102,
    "project_user_ids": [101, 103]
}

응답 예시

{
    "success": true,
    "message": "사용자가 그룹에서 삭제되었습니다."
}

그룹 사용자 목록 조회 StarterBiz

지정된 group_id에 속한 사용자 목록을 조회합니다.
결과에는 사용자 ID, 전화번호, 메모, 등록일자 정보가 포함되며, 페이징은 적용되지 않습니다.

요청 방식: GET

엔드포인트: /group/users/list

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

필수 group_id: 조회 대상 그룹의 고유 ID

에러 응답 설명

400 Bad Request

group_id가 누락된 경우

{"success": false, "error": "group_id는 필수입니다."}

404 Not Found

그룹에 속한 사용자가 없는 경우

{"success": false, "error": "그룹에 속한 사용자가 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 2,
    "group_users": [
        {
            "project_user_id": 101,
            "user_id": "john123",
            "phone": "010-1234-5678",
            "memo": "VIP 고객",
            "created_at": "2025-04-01 10:00"
        },
        {
            "project_user_id": 102,
            "user_id": "kimtester",
            "phone": "010-0000-1111",
            "memo": "",
            "created_at": "2025-04-02 11:00"
        }
    ]
}

사용자 푸시 발송

선택한 사용자들에게 푸시 메시지를 전송합니다.
즉시 발송 또는 예약 발송이 가능합니다.

요청 방식: POST

엔드포인트: /send/user

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 user_ids: 발송 대상 사용자 ID 배열 ([101, 102, ...])
필수 title: 푸시 제목
필수 message: 푸시 메시지 내용
선택 link: 클릭 시 이동할 링크 (https://로 시작해야 함)
선택 send_type: immediate (기본값) 또는 scheduled
선택 scheduled_at: 예약 발송 시간 (ISO 포맷, 예: 2025-04-19T14:00:00)

에러 응답 설명

400 Bad Request

필수값 누락, 잘못된 링크 형식, 예약 시간 오류 등

{"success": false, "message": "모든 항목을 입력해주세요."}
{"success": false, "message": "링크는 https://로 시작해야 합니다."}
{"success": false, "message": "예약 시간은 현재보다 이후여야 합니다."}

403 Forbidden

예약 발송 요청 시 현재 프로젝트 요금제가 Biz 이상이 아닌 경우

{"success": false, "message": "예약 발송은 Biz 요금제 이상에서만 사용 가능합니다."}

404 Not Found

대상 사용자의 푸시토큰이 없는 경우

{"success": false, "error": "대상 사용자의 푸시 토큰이 없습니다."}

500 Internal Server Error

푸시 전송 또는 로그 등록 중 서버 에러 발생 시

{"success": false, "error": "푸시 데이터 등록 중 오류 발생: ..."}

요청 예시

{
    "user_ids": [101, 102],
    "title": "알림 제목입니다",
    "message": "이것은 알림 메시지입니다.",
    "link": "https://example.com",
    "send_type": "immediate"
}

{
    "user_ids": [101, 102],
    "title": "알림 제목입니다",
    "message": "이것은 예약된 메시지입니다.",
    "link": "https://example.com",
    "send_type": "scheduled",
    "scheduled_at": "2025-04-19T14:00:00"
}

응답 예시

{
    "success": true,
    "message": "2건의 푸시가 전송되었습니다.",
    "push_group_id": 456,
    "total_count": 3,
    "success_count": 2,
    "fail_count": 1,
    "push": {
        "title": "알림 제목입니다",
        "message": "이것은 알림 메시지입니다.",
        "link": "https://example.com"
    }
}

{
    "success": true,
    "message": "3건의 푸시가 예약되었습니다.",
    "push_group_id": 456,
    "scheduled_at": "2025-04-19T14:00:00",
    "push": {
        "title": "알림 제목입니다",
        "message": "이것은 알림 메시지입니다.",
        "link": "https://example.com"
    }
}

그룹 사용자 푸시 발송

선택한 그룹에 속한 모든 사용자에게 푸시 메시지를 전송합니다.
즉시 발송 또는 예약 발송이 가능합니다.

요청 방식: POST

엔드포인트: /send/group

인증 필요: Authorization 헤더 (API Key)

요청 파라미터 (JSON)

필수 group_id: 발송 대상 그룹 ID
필수 title: 푸시 제목
필수 message: 푸시 메시지 내용
선택 link: 클릭 시 이동할 링크 (https://로 시작해야 함)
선택 send_type: immediate (기본값) 또는 scheduled
선택 scheduled_at: 예약 발송 시간 (ISO 포맷, 예: 2025-04-19T14:00:00)

에러 응답 설명

400 Bad Request

필수값 누락, 잘못된 링크 형식, 예약 시간 오류 등

{"success": false, "message": "모든 항목을 입력해주세요."}
{"success": false, "message": "링크는 https://로 시작해야 합니다."}
{"success": false, "message": "예약 시간은 현재보다 이후여야 합니다."}

403 Forbidden

예약 발송 요청 시 현재 프로젝트 요금제가 Biz 이상이 아닌 경우

{"success": false, "message": "예약 발송은 Biz 요금제 이상에서만 사용 가능합니다."}

500 Internal Server Error

푸시 전송 또는 로그 등록 중 서버 에러 발생 시

{"success": false, "error": "푸시 데이터 등록 중 오류 발생: ..."}

요청 예시

{
    "group_id": 102,
    "title": "알림 제목입니다",
    "message": "이것은 그룹 알림 메시지입니다.",
    "link": "https://example.com",
    "send_type": "immediate"
}

{
    "group_id": 102,
    "title": "알림 제목입니다",
    "message": "이것은 예약된 그룹 알림입니다.",
    "link": "https://example.com",
    "send_type": "scheduled",
    "scheduled_at": "2025-04-19T14:00:00"
}

응답 예시

{
    "success": true,
    "message": "2건의 푸시가 전송되었습니다.",
    "group_id": 102,
    "push_group_id": 457,
    "total_count": 3,
    "success_count": 2,
    "fail_count": 1,
    "push": {
        "title": "알림 제목입니다",
        "message": "이것은 알림 메시지입니다.",
        "link": "https://example.com"
    }
}

{
    "success": true,
    "message": "3건의 푸시가 예약되었습니다.",
    "group_id": 102,
    "push_group_id": 457,
    "scheduled_at": "2025-04-19T14:00:00",
    "push": {
        "title": "알림 제목입니다",
        "message": "이것은 알림 메시지입니다.",
        "link": "https://example.com"
    }
}

발송 상태 보고

특정 push_group_id에 대한 푸시 발송 결과를 요약 조회합니다.
총 발송 수, 성공 수, 실패 수, 실제 수신된 수, 수신 누락 수(성공했지만 수신확인 안된 건) 정보를 포함합니다.

요청 방식: GET

엔드포인트: /report/summary

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

필수 push_group_id: 조회 대상 푸시 그룹 ID

에러 응답 설명

400 Bad Request

push_group_id가 누락된 경우

{"success": false, "error": "push_group_id는 필수입니다."}

404 Not Found

전송된 데이터가 없는 경우

{"success": false, "error": "전송된 푸시 데이터가 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 1000,
    "success_count": 980,
    "fail_count": 20,
    "received_count": 0,
    "received_count": 760,
    "missed_count": 220
}

발송 결과 조회

지정된 push_group_id에 대한 발송 결과 목록을 조회합니다.
각 항목에는 사용자 ID, 전화번호, 플랫폼, 성공 여부, 실패 사유, 발송일시 및 수신일시 정보가 포함됩니다.
결과는 페이징 처리되어 반환됩니다.

요청 방식: GET

엔드포인트: /report/logs

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

필수 push_group_id: 조회 대상 푸시 그룹 ID
선택 page: 페이지 번호 (기본값: 1)
선택 is_success: 전송 성공 여부 ( Y [성공], N [실패] / 생략 시 전체 조회 )

에러 응답 설명

400 Bad Request

push_group_id 누락 또는 유효하지 않은 page 값

{"success": false, "error": "push_group_id는 필수입니다."}
{"success": false, "error": "유효한 page 값을 입력하세요 (1 이상의 정수)."}

404 Not Found

해당 그룹에 대한 발송 이력이 없는 경우

{"success": false, "error": "조회된 발송 이력이 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 3,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "push_group_id": 457,
    "is_success": null,
    "logs": [
        {
            "push_log_id": 640,
            "user_id": "john123",
            "phone": "010-1234-5678",
            "platform": "web",
            "is_success": 1,
            "fail_reason": null,
            "sent_at": "2025-04-17 14:30",
            "received_at": "2025-04-17 14:30"
        },
        {
            "push_log_id": 641,
            "user_id": "ascim13",
            "phone": "010-1542-7777",
            "platform": "web",
            "is_success": 1,
            "fail_reason": null,
            "sent_at": "2025-04-17 14:30",
            "received_at": null
        },
        {
            "push_log_id": 642,
            "user_id": "kimtester",
            "phone": "010-0000-1111",
            "platform": "android",
            "is_success": 0,
            "fail_reason": "InvalidToken",
            "sent_at": "2025-04-17 14:31",
            "received_at": null
        }
    ]
}

{
    "success": true,
    "total": 2,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "push_group_id": 457,
    "is_success": "Y",
    "logs": [
        {
            "push_log_id": 640,
            "user_id": "john123",
            "phone": "010-1234-5678",
            "platform": "web",
            "is_success": 1,
            "fail_reason": null,
            "sent_at": "2025-04-17 14:30",
            "received_at": "2025-04-17 14:30"
        },
        {
            "push_log_id": 641,
            "user_id": "ascim13",
            "phone": "010-1542-7777",
            "platform": "web",
            "is_success": 1,
            "fail_reason": null,
            "sent_at": "2025-04-17 14:30",
            "received_at": null
        }
    ]
}

{
    "success": true,
    "total": 1,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "push_group_id": 457,
    "is_success": "N",
    "logs": [
        {
            "push_log_id": 642,
            "user_id": "kimtester",
            "phone": "010-0000-1111",
            "platform": "android",
            "is_success": 0,
            "fail_reason": "InvalidToken",
            "sent_at": "2025-04-17 14:31",
            "received_at": null
        }
    ]
}

미수신 사용자 조회

push_group_id에 포함된 사용자 중 푸시 전송은 성공했지만 수신 확인이 되지 않은 사용자 목록을 조회합니다.
결과는 페이징 처리되어 반환되며, 사용자 ID, 전화번호, 플랫폼, 메시지 ID, 발송일시 등을 포함합니다.

요청 방식: GET

엔드포인트: /report/missed

인증 필요: Authorization 헤더 (API Key)

쿼리 파라미터

필수 push_group_id: 조회 대상 푸시 그룹 ID
선택 page: 페이지 번호 (기본값: 1)

에러 응답 설명

400 Bad Request

push_group_id 누락 또는 유효하지 않은 page 값

{"success": false, "error": "push_group_id는 필수입니다."}
{"success": false, "error": "유효한 page 값을 입력하세요 (1 이상의 정수)."}

404 Not Found

미수신 이력이 없는 경우

{"success": false, "error": "조회된 미수신 이력이 없습니다."}

500 Internal Server Error

서버 처리 중 예기치 않은 오류가 발생한 경우

{"success": false, "error": "조회 중 오류 발생: ..."}

응답 예시

{
    "success": true,
    "total": 1,
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total_pages": 1
    },
    "push_group_id": 457,
    "missed": [
        {
            "push_log_id": 641,
            "user_id": "ascim13",
            "phone": "010-1542-7777",
            "platform": "web",
            "sent_at": "2025-04-17 14:31",
            "resend_at": null
        }
    ]
}

미수신 푸시 재발송 Biz

발송에는 성공했지만 수신되지 않은 푸시 메시지를 다시 전송합니다.
재전송은 기존 발송 이력의 push_log_id를 기반으로 수행되며, 발송 실패이거나 이미 수신된 푸시는 재전송할 수 없습니다.

요청 방식: POST

엔드포인트: /report/resend/<push_log_id>

인증 필요: Authorization 헤더 (API Key)

에러 응답 설명

400 Bad Request

재전송이 불가능한 상태 (발송 실패 또는 이미 수신됨)

{"success": false, "error": "해당 로그는 발송에 실패한 기록입니다. 재전송할 수 없습니다.", "fail_reason": "Invalid token"}
{"success": false, "error": "해당 푸시는 이미 수신되어 재전송할 수 없습니다."}

404 Not Found

존재하지 않는 push_log_id인 경우

{"success": false, "error": "존재하지 않는 push_log_id입니다."}
{"success": false, "error": "해당 사용자의 토큰이 없습니다."}

500 Internal Server Error

재전송 처리 중 서버 오류 발생

{"success": false, "error": "재전송 중 오류 발생: ..."}

요청 예시

{
    "success": true,
    "message": "푸시가 재전송되었습니다.",
    "push_group_id": 123,
    "sent_at": "2025-04-17 19:00",
    "push": {
        "title": "알림 제목입니다",
        "message": "푸시 메시지입니다.",
        "link": "https://example.com"
    }
}

{
    "success": true,
    "message": "푸시 재전송에 실패했습니다.",
    "push_group_id": 123,
    "fail_reason": "Invalid token",
    "push": {
        "title": "알림 제목입니다",
        "message": "푸시 메시지입니다.",
        "link": "https://example.com"
    }
}