# SkyNotice - 完整文件

> SkyNotice 是企業多平台推播通知系統，支援 LINE、Facebook Messenger、Telegram、Email、APP Push、Web Push 六大平台。透過統一 API 介面，一次發送即可觸達所有已訂閱的會員。

## System Overview

SkyNotice 提供以下核心功能：

1. **多平台推播** - 支援 6 大通知平台，一次 API 呼叫同時發送
2. **會員管理** - 會員註冊、裝置綁定、通知訂閱偏好
3. **通知類別** - 自訂通知類別，會員可選擇性訂閱
4. **排程發送** - 透過 Cronjob 背景排程，非同步發送通知
5. **發送追蹤** - 各平台獨立追蹤發送狀態
6. **API 整合** - RESTful API 介面，支援 cURL、PHP、JavaScript、Python

## API Endpoint

```
POST https://skynotice.tw/api/notify
Content-Type: application/json
```

## Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| company_token | string | Company Token (from dashboard) |
| type_token | string | Notification type Token (from dashboard) |
| timestamp | integer | Unix timestamp for replay protection (valid within ±5 minutes) |
| title | string | Notification title |
| content | string | Notification content |

## Optional Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| weblink | string | URL to open when notification is clicked |
| other | string | Additional information |
| target_member_sn | integer | Specific member ID (0 or omit = all subscribers) |

## Response Format

### Success

```json
{
  "status": "success",
  "code": "OK",
  "message": "通知已成功建立",
  "data": { "notice_code": "aBcDeFgH12345678" }
}
```

### Error

```json
{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Error description"
}
```

## Error Codes

| Code | Description |
|------|-------------|
| METHOD_NOT_ALLOWED | Only POST method accepted |
| INVALID_CONTENT_TYPE | Content-Type must be application/json |
| EMPTY_BODY | Request body is empty |
| INVALID_JSON | Invalid JSON format |
| MISSING_TIMESTAMP | Missing timestamp parameter |
| INVALID_TIMESTAMP | Invalid timestamp format |
| TIMESTAMP_EXPIRED | Request expired (timestamp beyond ±5 minutes) |
| RATE_LIMIT_EXCEEDED | Too many requests (100 per token per minute) |
| MISSING_REQUIRED_FIELDS | Missing required fields |
| INVALID_TOKEN | Token verification failed |
| EMPTY_TITLE | Title cannot be empty |
| EMPTY_CONTENT | Content cannot be empty |

## Supported Platforms

| Platform | Binding Method | Push Method |
|----------|---------------|-------------|
| Facebook Messenger | Link binding via member dashboard | Facebook Send API |
| LINE | LINE Webhook + binding code | LINE Messaging API |
| Telegram | Telegram Bot binding | Telegram Bot API |
| Email | Member registration email | SMTP / Mail API |
| APP Push (iOS/Android) | Expo Push Notification | FCM (Android) / APNs (iOS) |
| Web Push | Browser subscription | Web Push Protocol (VAPID) |

## Web Push API

```
GET  https://skynotice.tw/api/webpush/vapid-key    # Get VAPID public key
POST https://skynotice.tw/api/webpush/subscribe     # Subscribe to push
POST https://skynotice.tw/api/webpush/unsubscribe   # Unsubscribe from push
```

## APP API

```
POST https://skynotice.tw/api/app/login             # APP login & device registration
GET  https://skynotice.tw/api/app/notifications      # Fetch notification history
```

## Code Examples

### cURL

```bash
curl -X POST https://skynotice.tw/api/notify \
  -H "Content-Type: application/json" \
  -d '{
    "company_token": "YOUR_COMPANY_TOKEN",
    "type_token": "YOUR_TYPE_TOKEN",
    "timestamp": '$(date +%s)',
    "title": "Test Notification",
    "content": "Hello from SkyNotice API"
  }'
```

### PHP

```php
$data = [
    "company_token" => "YOUR_COMPANY_TOKEN",
    "type_token"    => "YOUR_TYPE_TOKEN",
    "timestamp"     => time(),
    "title"         => "Test Notification",
    "content"       => "Hello from SkyNotice API"
];
$ch = curl_init("https://skynotice.tw/api/notify");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
```

### JavaScript

```javascript
const res = await fetch("https://skynotice.tw/api/notify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    company_token: "YOUR_COMPANY_TOKEN",
    type_token: "YOUR_TYPE_TOKEN",
    timestamp: Math.floor(Date.now() / 1000),
    title: "Test Notification",
    content: "Hello from SkyNotice API"
  })
});
const result = await res.json();
```

### Python

```python
import requests, time
result = requests.post("https://skynotice.tw/api/notify", json={
    "company_token": "YOUR_COMPANY_TOKEN",
    "type_token": "YOUR_TYPE_TOKEN",
    "timestamp": int(time.time()),
    "title": "Test Notification",
    "content": "Hello from SkyNotice API"
}).json()
```

## Security

- **Timestamp Validation**: Requests must include a Unix timestamp within ±5 minutes of server time
- **Rate Limiting**: 100 requests per company_token per minute
- **XSS Protection**: All input is sanitized before storage
- **Token Authentication**: company_token + type_token pair verification
- **Request Logging**: All API requests are logged for audit

## Pages

- [首頁](https://skynotice.tw): 系統介紹與功能說明
- [最新消息](https://skynotice.tw/news): 系統公告與更新
- [常見問題](https://skynotice.tw/question): FAQ
- [操作手冊](https://skynotice.tw/usermanual): 使用說明
- [隱私權政策](https://skynotice.tw/privacy)
- [服務條款](https://skynotice.tw/terms)
- [聯絡我們](https://skynotice.tw/contact)