API 使用教學

從第一個請求,
到您的網站與 App。

取得 API Key,讓您的後端轉送請求,再把 JSON 結果呈現在產品中。以下以姓名五格示範,也可套用到其他命理類型。

01・開始使用

註冊並保存您的 API Key

  1. 註冊會員,系統會自動建立一組預設 API Key。
  2. 註冊後,在 API Keys 頁複製完整 Key 並保存;完整內容只在建立時提供。
  3. 將 Key 放在您後端的環境變數 FORTUNE_API_KEY,將本站部署網域放在 FORTUNE_BASE_URL。
  4. 在終端機送出下面的請求,成功後會取得 JSON。

範例網域需替換為本站的實際網址;本機測試可用 http://localhost:3322。瀏覽器程式與 App 安裝包皆不放完整 API Key。

cURL・測試正式會員接口
# 在您的伺服器或本機終端機設定,請替換網域與 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"}'
02・網頁串接

網頁 → 您的後端 → 命理 API

使用者在網頁輸入資料,由您網站的後端驗證登入與使用權限,再帶 API Key 呼叫 /api/proxy/name。您的後端收到 JSON 後,回傳給網頁顯示。

瀏覽器 JavaScript・呼叫自己的網站
// 網頁只呼叫自己網站的後端;使用既有登入 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_ 前綴。

您的後端・只在伺服器讀取 API Key
// 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」確認。

03・App 串接

App 使用自己的登入 token

App 登入您的系統後,帶自己的使用者 token 呼叫您的後端。後端需支援並驗證該 token,再由伺服器使用 API Key 呼叫命理 API。這個 token 與本平台 API Key 是兩種不同的憑證。

Flutter・POST JSON 到您的後端
// 先執行 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 也採同樣的後端轉送流程。

04・接口與參數

六種能力,同一組 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"
}
05・用量與紀錄

回控制台查看每一次呼叫

登入後,從左側「API 呼叫記錄」查看自己的接口、狀態碼、呼叫時間與耗時,可依接口及狀態篩選。額度與每分鐘限制由會員方案決定。

  • 200:成功取得結果,可解析 JSON。
  • 401/403:缺少或無效的 Key、Key 已撤銷,或帳號/訂閱無法使用。
  • 429:超過月額度或每分鐘限制,請降低頻率或確認方案。
  • 502/504:排盤服務暫時失敗或逾時,稍後再試。

正式產品使用 /api/proxy/*;/api/demo/* 僅供商用示範,超過每日上限會回固定預設內容,不代表您的輸入結果,也不寫入會員呼叫紀錄。

程式開發・外包合作

有產品想法,程式交給我。

想把命理 API 做成網站、App 或完整會員服務?我可以協助需求規劃、介面設計、API 串接、會員後台與上線部署,讓您的想法成為可使用的產品。

網站開發App 開發API 整合會員與管理後台

洽談前可先準備功能需求、參考畫面、使用平台、預算範圍與預計時程;開發內容、費用與交付項目依專案需求評估。