從第一個請求,
到您的網站與 App。
取得 API Key,讓您的後端轉送請求,再把 JSON 結果呈現在產品中。以下以姓名五格示範,也可套用到其他命理類型。
註冊並保存您的 API Key
- 註冊會員,系統會自動建立一組預設 API Key。
- 註冊後,在 API Keys 頁複製完整 Key 並保存;完整內容只在建立時提供。
- 將 Key 放在您後端的環境變數
FORTUNE_API_KEY,將本站部署網域放在FORTUNE_BASE_URL。 - 在終端機送出下面的請求,成功後會取得 JSON。
範例網域需替換為本站的實際網址;本機測試可用 http://localhost:3322。瀏覽器程式與 App 安裝包皆不放完整 API Key。
# 在您的伺服器或本機終端機設定,請替換網域與 Key
export FORTUNE_BASE_URL="https://fate-api.allcares.app"
export FORTUNE_API_KEY="貼上您的完整_API_Key"
curl "$FORTUNE_BASE_URL/api/proxy/name" \
-H "X-API-Key: $FORTUNE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"surname":"楊","givenName":"德","gender":"M"}'網頁 → 您的後端 → 命理 API
使用者在網頁輸入資料,由您網站的後端驗證登入與使用權限,再帶 API Key 呼叫 /api/proxy/name。您的後端收到 JSON 後,回傳給網頁顯示。
// 網頁只呼叫自己網站的後端;使用既有登入 Cookie
async function calculateName(surname, givenName) {
const response = await fetch('/api/fortune/name', {
method: 'POST',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ surname, givenName, gender: 'M' }),
});
const data = await response.json();
if (!response.ok || data.success === false) {
throw new Error(data.error ?? '試算失敗');
}
return data; // 姓名結果使用 data.grids、data.strokes
}展開 Next.js 後端轉送範例
此範例需要您的專案實作 authorizeProductUser,用來驗證 Cookie 或 App token、權限與呼叫頻率。它不是本站提供的套件;也不要讓轉送路由成為未驗證登入的公開接口。環境變數不加 NEXT_PUBLIC_ 前綴。
// Next.js:app/api/fortune/name/route.ts
import { NextResponse } from 'next/server';
// 此函式由您的專案實作:驗證登入 Cookie 或 App token,
// 檢查使用權限與每位使用者的呼叫頻率,失敗時回傳 null。
import { authorizeProductUser } from '@/lib/product-auth';
export async function POST(request: Request) {
if (!(await authorizeProductUser(request))) {
return NextResponse.json({ error: '請先登入或稍後再試' }, { status: 403 });
}
const key = process.env.FORTUNE_API_KEY;
const base = process.env.FORTUNE_BASE_URL;
if (!key || !base) {
return NextResponse.json({ error: 'API 尚未設定' }, { status: 503 });
}
let input;
try { input = await request.json(); }
catch { return NextResponse.json({ error: 'JSON 格式錯誤' }, { status: 400 }); }
const { surname, givenName, gender } = input ?? {};
if (typeof surname !== 'string' || !surname.trim() || surname.length > 10 ||
typeof givenName !== 'string' || !givenName.trim() || givenName.length > 10 ||
!['M', 'F'].includes(gender)) {
return NextResponse.json({ error: '姓名或性別格式錯誤' }, { status: 400 });
}
try {
const result = await fetch(new URL('/api/proxy/name', base), {
method: 'POST',
headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
body: JSON.stringify({ surname, givenName, gender }),
cache: 'no-store',
signal: AbortSignal.timeout(15000),
});
return new NextResponse(result.body, {
status: result.status,
headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },
});
} catch {
return NextResponse.json({ error: 'API 暫時無法連線' }, { status: 502 });
}
}將 data.grids 的五格數值與 data.strokes 的筆劃資料呈現在您的 UI;其他 API 的回應欄位可在商用示範的「查看原始 JSON」確認。
App 使用自己的登入 token
App 登入您的系統後,帶自己的使用者 token 呼叫您的後端。後端需支援並驗證該 token,再由伺服器使用 API Key 呼叫命理 API。這個 token 與本平台 API Key 是兩種不同的憑證。
// 先執行 flutter pub add http
import 'dart:convert';
import 'package:http/http.dart' as http;
Future<Map<String, dynamic>> calculateName({
required Uri yourBackendUrl, // 例如 https://您的後端/api/fortune/name
required String userAccessToken, // 您自己的 App 登入 token
required String surname,
required String givenName,
}) async {
final response = await http.post(
yourBackendUrl,
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer $userAccessToken',
},
body: jsonEncode({ 'surname': surname, 'givenName': givenName, 'gender': 'M' }),
).timeout(const Duration(seconds: 20));
final data = jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
if (response.statusCode < 200 || response.statusCode >= 300 || data['success'] == false) {
throw Exception(data['error'] ?? '試算失敗');
}
return data;
}請將後端網址換成 App 可連線的 HTTPS 網址。Android 須在 AndroidManifest.xml 加入 android.permission.INTERNET。依據 Flutter 官方網路教學使用 http 套件;iOS、Android 原生 App 也採同樣的後端轉送流程。
六種能力,同一組 Key
以下接口皆使用 POST、Content-Type: application/json 與 X-API-Key。星盤的日期時間為出生地當地時間,utcOffsetMinutes 是該日期的 UTC 時差分鐘數;台北為 480。
| 類型 | 接口 | JSON 範例 |
|---|---|---|
| 姓名五格 | /api/proxy/name | {
"surname": "楊",
"givenName": "德",
"gender": "M"
} |
| 八字 | /api/proxy/bazi | {
"sy": 1990,
"sm": 6,
"sd": 10,
"sh": 8,
"smin": 30,
"gender": "M"
} |
| 紫微斗數 | /api/proxy/zwds | {
"sy": 1990,
"sm": 6,
"sd": 10,
"sh": 8,
"gender": "M"
} |
| 西洋星盤 | /api/proxy/star | {
"sy": 1990,
"sm": 6,
"sd": 10,
"sh": 8,
"smin": 30,
"birthPlace": "台北",
"latitude": 25.033,
"longitude": 121.5654,
"utcOffsetMinutes": 480
} |
| 奇門遁甲 | /api/proxy/qimen | {
"dateTime": "2026-08-22T15:00:00"
} |
| 籤詩神卦 | /api/proxy/fortune-poem | {
"type": "guanyin_100"
} |
回控制台查看每一次呼叫
登入後,從左側「API 呼叫記錄」查看自己的接口、狀態碼、呼叫時間與耗時,可依接口及狀態篩選。額度與每分鐘限制由會員方案決定。
- 200:成功取得結果,可解析 JSON。
- 401/403:缺少或無效的 Key、Key 已撤銷,或帳號/訂閱無法使用。
- 429:超過月額度或每分鐘限制,請降低頻率或確認方案。
- 502/504:排盤服務暫時失敗或逾時,稍後再試。
正式產品使用 /api/proxy/*;/api/demo/* 僅供商用示範,超過每日上限會回固定預設內容,不代表您的輸入結果,也不寫入會員呼叫紀錄。
有產品想法,程式交給我。
想把命理 API 做成網站、App 或完整會員服務?我可以協助需求規劃、介面設計、API 串接、會員後台與上線部署,讓您的想法成為可使用的產品。
洽談前可先準備功能需求、參考畫面、使用平台、預算範圍與預計時程;開發內容、費用與交付項目依專案需求評估。