Push API 문서

Push API 문서

웹 푸시 알림 발송을 위한 REST API 문서

📖 API 개요

Push API를 사용하여 웹 브라우저로 실시간 푸시 알림을 발송할 수 있습니다. 이 API는 RESTful 방식으로 설계되었으며, JSON 형식의 데이터를 사용합니다.

기본 URL

https://api.pushmanager.kr

인증 방식

모든 API 요청에는 다음 헤더가 필요합니다:

  • Content-Type: application/json
  • X-API-Key: {your-api-key}

POST 단일 푸시 발송

하나의 구독자에게 푸시 알림을 발송합니다.

https://api.pushmanager.kr/api/push/single

요청 파라미터

파라미터 타입 필수 설명
subscription object 필수 푸시 구독 정보
├── endpoint string 필수 푸시 서비스 엔드포인트 URL
└── keys object 필수 암호화 키 정보
├── p256dh string 필수 P256DH 공개키
└── auth string 필수 인증 비밀키
payload object 필수 푸시 알림 내용
├── title string 필수 알림 제목 (최대 100자)
├── body string 필수 알림 본문 (최대 300자)
├── icon string 선택 알림 아이콘 URL
└── url string 선택 클릭 시 이동할 URL
options object 선택 푸시 옵션
└── TTL integer 선택 생존 시간(초), 최대 2419200(4주)

PHP cURL 사용 예제

<?php
function sendSinglePush($subscription, $payload, $options = []) {
    $api_url = 'https://api.pushmanager.kr';
    $api_key = 'your-api-key-here';
    
    $data = [
        'subscription' => $subscription,
        'payload' => $payload,
        'options' => $options
    ];
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $api_url . '/api/push/single',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $api_key
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception('Push notification failed: ' . $response);
    }
}

// 사용 예제
$subscription = [
    'endpoint' => 'https://fcm.googleapis.com/fcm/send/abc123...',
    'keys' => [
        'p256dh' => 'BFYEOn4vQKKXYCGHnt9wCwPpvR7XJm8...',
        'auth' => 'tBHItJh5u9CqcyWMcJQPwQ=='
    ]
];

$payload = [
    'title' => '새로운 메시지',
    'body' => '김철수님이 메시지를 보냈습니다.',
    'icon' => '/icon-192x192.png',
    'url' => 'https://example.com/messages'
];

try {
    $result = sendSinglePush($subscription, $payload);
    echo 'Push sent successfully: ' . json_encode($result);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

?>>

응답 예제

성공 응답 (200 OK)
{
  "success": true,
  "message": "Push notification sent successfully",
  "data": {
    "sent": 1,
    "failed": 0,
    "statusCode": 201,
    "payloadSize": 256
  }
}

POST 다중 푸시 발송

여러 구독자에게 동시에 푸시 알림을 발송합니다. 최대 1,000명까지 한 번에 발송할 수 있습니다.

https://api.pushmanager.kr/api/push/multiple

요청 파라미터

파라미터 타입 필수 설명
subscriptions array 필수 푸시 구독 정보 배열 (1-1000개)
payload object 필수 모든 사용자에게 동일하게 발송할 푸시 내용
options object 선택 푸시 옵션

PHP cURL 사용 예제

<?php
function sendMultiplePush($subscriptions, $payload, $options = []) {
    $api_url = 'https://api.pushmanager.kr';
    $api_key = 'your-api-key-here';
    
    $data = [
        'subscriptions' => $subscriptions,
        'payload' => $payload,
        'options' => $options
    ];
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $api_url . '/api/push/multiple',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'X-API-Key: ' . $api_key
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception('Multiple push notification failed: ' . $response);
    }
}

// 사용 예제
$subscriptions = [
    [
        'endpoint' => 'https://fcm.googleapis.com/fcm/send/user1...',
        'keys' => [
            'p256dh' => 'BFYEOn4vQKKXYCGHnt9wCwPpvR7XJm8...',
            'auth' => 'tBHItJh5u9CqcyWMcJQPwQ=='
        ]
    ],
    [
        'endpoint' => 'https://fcm.googleapis.com/fcm/send/user2...',
        'keys' => [
            'p256dh' => 'BAbCdEfGhIjKlMnOpQrStUvWxYz123...',
            'auth' => 'xYz123AbC456DeF789GhI=='
        ]
    ]
    // ... 최대 1000개까지
];

$payload = [
    'title' => '공지사항',
    'body' => '새로운 업데이트가 출시되었습니다.',
    'icon' => '/icon-192x192.png',
    'url' => 'https://example.com/updates'
];

try {
    $result = sendMultiplePush($subscriptions, $payload);
    echo 'Multiple push sent successfully: ' . json_encode($result);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

?>>

응답 예제

성공 응답 (200 OK)
{
  "success": true,
  "message": "Multiple push notifications processed",
  "data": {
    "total": 100,
    "sent": 95,
    "failed": 5,
    "successRate": 95.0,
    "errorStats": {
      "expired": 3,
      "client_error": 2
    },
    "processingTime": 1250
  }
}

⚠️ 오류 코드

API 호출 시 발생할 수 있는 오류 코드와 해결 방법입니다.

상태 코드 설명 해결 방법
200 성공 요청이 정상적으로 처리됨
400 잘못된 요청 요청 데이터 형식을 확인하세요
401 인증 실패 API 키를 확인하세요
403 접근 권한 없음 서비스가 비활성화되었거나 Origin이 일치하지 않음
429 요청 제한 초과 시간당 요청 제한을 초과했습니다. 잠시 후 다시 시도하세요
500 서버 오류 서버에 일시적인 문제가 발생했습니다

오류 응답 예제

인증 실패 (401)
{
  "success": false,
  "message": "Invalid API key",
  "code": "API_KEY_INVALID",
  "timestamp": "2025-06-30T12:00:00Z"
}

오류 처리 예제

<?php
function handlePushResponse($response, $httpCode) {
    $data = json_decode($response, true);
    
    switch ($httpCode) {
        case 200:
            return [
                'success' => true,
                'data' => $data
            ];
            
        case 400:
            return [
                'success' => false,
                'error' => '잘못된 요청: ' . $data['message'],
                'code' => 'BAD_REQUEST'
            ];
            
        case 401:
            return [
                'success' => false,
                'error' => 'API 키가 유효하지 않습니다.',
                'code' => 'UNAUTHORIZED'
            ];
            
        case 429:
            return [
                'success' => false,
                'error' => '요청 제한을 초과했습니다. 잠시 후 다시 시도하세요.',
                'code' => 'RATE_LIMIT'
            ];
            
        default:
            return [
                'success' => false,
                'error' => '알 수 없는 오류: ' . $response,
                'code' => 'UNKNOWN_ERROR'
            ];
    }
}

?>>

📋 제한사항 및 정책

제한 항목 제한값 설명
푸시 발송 1분당 100회 API 키별 푸시 발송 제한
제목 길이 최대 100자 푸시 알림 제목
내용 길이 최대 300자 푸시 알림 본문
다중 발송 최대 1000명 한 번에 발송 가능한 최대 구독자 수
홈
게시판
공지사항
로그인