新創圓夢網資料交換 API 說明文件

創業新聞 - 版本 v1

回首頁

1. 概述與基礎資訊

1.1 概述

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

1.2 基礎 URL (Base URL)

所有新聞 API 資源請求的共同起始網址。請根據串接環境使用對應的 URL。

正式機 (Production):

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

測試機 (Staging):

https://w2.careernet.org.tw/api/news/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):

格式建議：廠商內容的ID， 1~10 位英數混和。若不足 10 位請向左補零。

{
  "content_id": "ABC123DEF9", // 必填，1~10 位英數混和流水號 (廠商平台 ID)
  "news_type": "新聞快訊", // 必填，新聞類型 (新聞快訊/創業專欄/公告)
  "title": "無人機技術突破，開創產業新格局", // 必填，標題
  "summary": "無人機在農業、物流與監控領域的應用日益成熟。", // 選填，摘要
  "content": "隨著人工智慧與電池技術的進步...", // 必填，內文
  "publish_date": 1729094400, // 必填，發佈時間 (Unix Timestamp)
  "source": "CYCDA", // 必填，資料來源代號 (須在白名單內)
  "url": "https://example.com/drone-tech", // 必填，原始文章網址
  "tags": "無人機,技術,AI,創新", // 選填，標籤 (以逗號分隔，最多 5 組)
  "status": 1, // 選填，狀態 (1: 啟用)
  "image_url": "https://placehold.co/600x400/..." // 選填，圖片網址
}

成功回應 (201 Created):

返回 submission_id (追蹤狀態用) 及您提供的 content_id (英數混和 ID)。

PUT /{content_id} (修改新聞資料)

用途：根據 URL 中的 英數混和流水號 修改已存在的資料。

完整路徑:

PUT /{英數混和流水號}

請求內容 (Request Body):

與 POST 格式相同，但 URL 中的 ID 必須與 Payload 中的 content_id（英數混和 ID）一致。

{
  "content_id": "ABC123DEF9", // 必須是已存在的英數混和 ID，且與 URL 匹配
  "source": "CYCDA", // 必填，用於驗證權限
  // ... 其他 POST 必填欄位仍需提供，以通過驗證 ...
  "title": "無人機技術突破，開創產業新格局 - (已更新)", 
  "content": "詳細內容...",
  "publish_date": 1729094400,
  "url": "https://example.com/drone-tech-update"
}

DELETE /{content_id} (刪除新聞資料)

用途：根據 URL 中的 英數混和流水號 刪除資料。

完整路徑:

DELETE /{英數混和流水號}

請求內容 (Request Body):

因後端驗證機制要求，**必須**傳送包含所有必填欄位 (即使是佔位符) 的 JSON 主體。

{
  "content_id": "ABC123DEF9", // 必填，與 URL 中的英數混和 ID 一致
  "source": "CYCDA", // 必填，用於權限驗證
  // 以下為後端驗證機制所要求的必填欄位 (請帶有效值作為佔位符)
  "title": "DELETE Placeholder",
  "content": "DELETE Placeholder Content",
  "publish_date": 1729094400,
  "url": "https://delete-placeholder.com/valid-url"
}

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

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

完整路徑:

GET /record/{submission_id}

回應 (200 OK):

返回該筆 submission 的處理狀態 (submission_status, submission_message 等)。

4. 錯誤處理與回應碼

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

5. 資料模型 - 創業新聞 (News)

適用於 POST/PUT/DELETE 請求內容的欄位定義。必填欄位以 ✓ 標示。

欄位名稱 類型 必填 (POST/PUT) 說明 限制/格式
content_id string ✓ 廠商平台的資料 ID。 必須是 1 到 10 位英數混和流水號 (字串格式)。若不足 10 位請向左補零。
news_type string ✓ 新聞類型。 限定值：新聞快訊 / 創業專欄 / 公告。
預設為「新聞快訊」。
title string ✓ 新聞標題。 長度限制：≤ 45 個中文字 (約 90 個英文字元)。
備註：必須是純文字。
summary string 否 新聞摘要/內容前言。 最大長度 100 字元。
備註：必須是純文字。
content string ✓ 新聞內容說明。 內容長度上限為 6000 字元。
備註：可包含基本的 HTML 標籤，例如：<p>, <br>, <strong>/<b>, <em>/<i>, <ul>, <ol>, <li>。
publish_date integer ✓ 發佈時間。 必須是有效的 UNIX Timestamp (秒級)。
source string ✓ 資料來源代號。 最大長度 10 字元。必須在白名單內 (例如：CYCDA, NTACADEMY, INCUBATOR)。
備註：申請API時，會提供。
url string ✓ 原始新聞網址。 必須是合法 URL 格式。
備註：必須以 https:// 開頭。
tags string 否 關鍵字標籤。 以逗號 (,) 分隔，最多五組標籤。
status integer 否 資料狀態碼。 接受數值 1 (啟用)、0(關閉)。
image_url string 否 新聞配圖的網址。 必須是有效的 URL，URL 錯誤或空白時將使用系統預設圖片。
備註：必須以 https:// 開頭。

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

以下為使用 PHP cURL 提交新增新聞資料的範例。請注意 content_id 必須是廠商的 英數混和流水號。

<?php
// 替換為您的實際金鑰與 Payload 內容
$apiKeyId = "CYCDA";
$apiSecret = "7f336e7e8b6264cdd82bd54827fcae03b3043cc253358c6fdac83811fbde4b8a";
$baseUrl = "https://startup.sme.gov.tw/api/news/v1"; // 使用正式機 URL

// 範例：廠商平台資料ID為 ABC123DEF9 (10位英數混和字串)
$payloadData = [
    "content_id" => "ABC123DEF9", // 必須是英數混和字串 (1~10位)
    "news_type" => "新聞快訊",
    "title" => "無人機技術突破",
    "summary" => "應用日益成熟。",
    "content" => "詳細內容，可包含 <strong>粗體</strong> 和 <p>段落</p> 等基本 HTML 標籤。",
    "publish_date" => time(), // 使用當前 UNIX 時間戳
    "source" => "CYCDA",
    "url" => "https://example.com/drone-tech",
    "tags" => "無人機,技術",
    "status" => 1
];

$payload = json_encode($payloadData);
$fullUrl = $baseUrl . "/"; // POST 到 Base URL

$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);
?>