新創圓夢網 API 串接說明文件

1. 概述與基礎資訊

1.1 概述

本文件說明如何串接圓夢網的「近期活動 (Events)」資料交換 API。此 API 允許合作夥伴透過標準的 RESTful 介面，以 JSON 格式新增、修改、刪除活動資料，並查詢資料處理狀態。

1.2 基礎 URL (Base URL)

所有活動 API 資源請求的共同起始網址。

正式機 (Production):

http://startup.sme.gov.tw/api/event/v1

測試機 (Staging):

https://w2.careernet.org.tw/api/event/v1

2. 身份驗證

所有 API 請求必須在 HTTP Header 中包含您的 API Key ID 與 API Key Secret，以進行身份驗證。

驗證 Header 格式

X-API-KEY: {您的 API Key ID}:{您的 API Key Secret}

其他必要 Header

Content-Type: application/json

3. 資源操作端點

POST / (新增活動資料)

用途：提交一筆新的活動資料進行處理。

完整路徑:

POST /

請求內容 (Request Body):

{
  "content_id": "1729094400", // 必填，活動的外部識別碼 (API 驗證用)
  "event_title": "創業家交流會：區塊鏈應用趨勢", // 必填，活動標題
  "content": "<p>活動內容，可包含 HTML 標籤。</p>", // 必填，活動內容 (純 HTML)
  "start_date_time": 1729094400, // 必填，開始時間 (Unix Timestamp，秒)
  "end_date_time": 1729098000, // 必填，結束時間 (Unix Timestamp，秒)
  "is_paid": false, // 選填，是否收費 (預設 false)
  "type": "線上", // 必填，活動類型
  "location": "", // 有條件必填：若 type 非 線上 則必填
  "County": "", // 有條件必填：若 type 非 線上 則必填
  "address": "", // 有條件必填：若 type 非 線上 則必填
  "longitude": 121.6146, // 選填，經度
  "latitude": 25.0561, // 選填，緯度
  "organizer": "INCUBATOR", // 必填，主辦單位
  "registration_url": "https://example.com/blockchain-event-reg", // 必填，報名網址
  "image_url": "https://placehold.co/600x400/...", // 選填，圖片網址
  "url": "https://example.com/blockchain-event", // 必填，原始活動網址
  "source": "CYCDA", // 必填，資料來源代號
  "tags": "區塊鏈,創業,新創,交流" // 選填，標籤 (以逗號分隔)
}

成功回應 (200 OK):

成功提交後，會返回一個 submission_id 用於追蹤處理狀態。

PUT /{content_id} (修改活動資料)

用途：根據 content_id 修改已存在的資料。

完整路徑:

PUT /{content_id}

請求內容 (Request Body):

與 POST 格式相同，但 content_id 必須與 URL 中的 content_id 一致。

DELETE /{content_id} (刪除活動資料)

用途：根據 content_id 刪除資料。

完整路徑:

DELETE /{content_id}

請求內容 (Request Body):

不需請求內容 (No Request Body)。

GET /record/{submission_id} (查詢處理狀態)

用途：查詢 POST/PUT/DELETE 請求返回的 submission_id 的處理進度。

完整路徑:

GET /record/{submission_id}

回應 (200 OK):

返回該筆 submission 的處理狀態 (e.g., pending, processing, completed, failed)。

4. 錯誤處理與回應碼

API 遵循標準 HTTP 狀態碼，並在錯誤時返回包含詳細訊息的 JSON 主體。

200 OK: 請求成功。
401 Unauthorized: API Key ID 或 Secret 錯誤，或格式不正確。
404 Not Found: 請求的資源 (如 content_id 或 submission_id) 不存在。
400 Bad Request: 請求內容格式錯誤或資料驗證失敗 (例如：必填欄位遺失)。
429 Too Many Requests: 達到頻率限制 (Rate Limit)。

5. 資料模型 - 近期活動 (Events)

適用於 POST/PUT 請求內容的欄位定義。必填欄位以 ✓ 標示，有條件必填以 C 標示。

欄位名稱	類型	必填	說明	限制/格式
content_id	string	✓	廠商平台的資料 ID。	格式建議：`廠商內容的ID， 1~10 位英數混和。若不足 10 位請向左補零。`
event_title	string	✓	活動標題。	長度限制：≤ 45 個中文字。提交前需移除 HTML 標籤。
content	string	✓	活動內容說明。	僅可傳遞純 HTML 內容。長度限制：≤ 6000 字元。
start_date_time	integer	✓	活動開始時間。	必須為 UNIX Timestamp (秒級，非毫秒)。
end_date_time	integer	✓	活動結束時間。	必須為 UNIX Timestamp (秒級)，且嚴格 > `活動開始時間`。
is_paid	boolean	否	活動是否收費。	`true` → 收費 / `false` → 免費。空值預設為免費。
type	string	✓	活動類型。	允許值：`線上` / `活動` / `課程` / `競賽`。
location	string	C	活動地點名稱 (例如：南港展覽館)。	若 `type` 非 `線上` 則必填。
County	string	C	縣市名稱。	若 `type` 非 `線上` 則必填，且須在系統白名單內。
address	string	C	活動地址。	若 `type` 非 `線上` 則必填（需包含巷弄號樓）。
longitude	number	否	活動地點經度。	必須為數值，小數點後最多四位。範例: `121.6146`
latitude	number	否	活動地點緯度。	必須為數值，小數點後最多四位。範例: `25.0561`
organizer	string	✓	主辦單位名稱。
registration_url	string	✓	活動報名網址。	必須是合法 URL 格式。
image_url	string	否	活動配圖的網址。	URL 錯誤時將使用預設圖片。
url	string	✓	原始活動網址。	必須是合法 URL 格式。備註：必須以 https:// 開頭。
source	string	✓	資料來源代號。	最大長度 10 字元。必須在白名單內 (例如：CYCDA, NTACADEMY, INCUBATOR)。備註：申請API時，會提供。
tags	string	否	關鍵字標籤。	半形逗號分隔，最多五組。

6. 程式碼範例 (POST - PHP cURL 實現)

以下為使用 PHP cURL 提交新增活動資料的範例。

<?php
// 替換為您的實際金鑰與 Payload 內容
$apiKeyId = "CYCDA";
$apiSecret = "6fecbc1104e20e28f17e7a4a7789cc17a5288c8382031e460729a3d25bcd0624";
$baseUrl = "https://w2.careernet.org.tw/api/event/v1";

// 範例：必須是 1 到 10 位英數混和流水號 (字串格式)。若不足 10 位請向左補零。
$event_id_serial = time();
$content_id = $event_id_serial;

// 設置活動時間 (當前時間 + 1 小時)，確保為秒級時間戳
$startTime = time();
$endTime = $startTime + 3600;

$payloadData = [
    "content_id" => $content_id, // 修正：Payload 中的 ID 欄位名稱應為 content_id
    "event_title" => "創業家交流會：區塊鏈應用趨勢",
    "content" => "<p>本交流會旨在提供一個平台，讓新創團隊與區塊鏈技術專家進行深度對話。</p>",
    "start_date_time" => $startTime,
    "end_date_time" => $endTime,
    "is_paid" => false,
    "type" => "線上",
    "location" => "N/A", // type為線上時，地點資訊可填 N/A 或空字串
    "County" => "N/A",
    "address" => "N/A",
    "longitude" => 121.6146,
    "latitude" => 25.0561,
    "organizer" => "INCUBATOR", // 修正：此欄位為必填
    "registration_url" => "https://example.com/blockchain-event-reg",
    "image_url" => "https://placehold.co/600x400/000000/FFFFFF?text=Event",
    "url" => "https://example.com/blockchain-event",
    "source" => "CYCDA",
    "tags" => "區塊鏈,創業,新創,交流"
];

$payload = json_encode($payloadData);
$fullUrl = $baseUrl . "/";

$headers = [
    'Content-Type: application/json',
    'X-API-KEY: ' . $apiKeyId . ':' . $apiSecret
];

$ch = curl_init($fullUrl);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo "cURL 錯誤: " . curl_error($ch) . "\n";
} else {
    echo "HTTP 狀態碼: " . $httpCode . "\n";
    echo "伺服器回應: " . $response . "\n";
}

curl_close($ch);
?>