← 回到神社

海上許願神社

API 文件

網站以外的程式（你自己的頁面、手機 App、命令列）可以透過這裡的端點讀取資料。需要登入的端點要帶登入權杖，每個人只拿得到自己的資料。

基本資訊

項目內容
網址開頭https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1
格式JSON（UTF-8）
跨網域允許所有網站呼叫（Access-Control-Allow-Origin: *）。靠權杖辨認身分，不靠 cookie
版本網址裡的 /v1 是版本號。之後改了回應格式會開 /v2，/v1 照常可以用
使用量限制每個帳號 10 分鐘內最多掛 5 塊繪馬（超過回 429）；每塊繪馬每人只能祈願一次（重複回 409）

登入權杖

需要登入的端點，請求要帶這個標頭：

Authorization: Bearer <access token>

權杖是在網站上登入成功時拿到的一段字串（JWT），一小時後過期；網站會自動換新。自己的程式要取得權杖，最簡單的方法是在網站登入後，用下面「試呼叫」的「複製我的權杖」。

權杖等於你一小時內的登入狀態：拿到的人可以用你的身分讀你的資料。不要貼到聊天、文件或公開的程式碼裡。

端點

方法路徑需要登入說明
GET/v1/wishes不用繪馬牆，新的在前，可以分頁
GET/v1/wishes/<id>不用一塊繪馬
POST/v1/wishes需要掛一塊繪馬
POST/v1/wishes/<id>/prayers需要為一塊繪馬祈願
GET/v1/me（或 /me）需要我的參拜紀錄

網址都接在 https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1 後面，例如 https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1/v1/wishes。

GET /v1/wishes　繪馬牆

不用登入。參數 limit：一次幾塊，1–50，預設 20。before：拿下一頁時，把上一頁回傳的 next 原樣帶回來（一串代碼，不用自己組）。

curl "https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1/v1/wishes?limit=2"
{
  "wishes": [
    { "id": "…", "text": "家裡的貓活到二十歲。", "by": "Mia", "votes": 18, "at": "2026-10-22T15:00:00Z" },
    { "id": "…", "text": "學會游泳，夏天去綠島浮潛。", "by": "阿哲", "votes": 12, "at": "2026-10-22T14:58:00Z" }
  ],
  "next": "MjAyNi0xMC0yMlQxNDo1ODowMFp8NGYx…"
}

next 是 null 代表沒有下一頁。

POST /v1/wishes　掛一塊繪馬

curl -X POST https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1/v1/wishes \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"明年春天去京都看櫻花。","by":"小林"}'

願望 1–40 字；署名最多 12 字，不填就是「匿名」。成功回 201 和這塊繪馬。資料庫會再檢查一次字數，前端的限制不算數。

POST /v1/wishes/<id>/prayers　祈願

curl -X POST https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1/v1/wishes/<id>/prayers -H "Authorization: Bearer <access token>"

成功回 201 和最新的祈願數 {"ok":true,"votes":43}。同一個帳號再祈願一次回 409。

GET /v1/me　我的參拜紀錄

回傳登入者自己掛過的繪馬（wishes）與祈願過的繪馬（prayers），新的在前。查詢經過資料表的權限檢查（RLS），就算知道別人的 id，也拿不到別人的紀錄。

curl -i https://xfmyjkyivqxnbpkczdgb.supabase.co/functions/v1/me \
  -H "Authorization: Bearer <access token>"

成功（200）：

{
  "user": { "id": "4f1c…", "email": "you@example.com" },
  "wishes": [
    { "id": "9a2e…", "text": "希望今年冬天能去北海道，看一次真正的雪。", "by": "雅婷", "votes": 43, "at": "2026-10-22T15:20:11Z" }
  ],
  "prayers": [
    { "id": "00000000-0000-4000-8000-000000000001", "text": "阿嬤的膝蓋手術順利，明年還能一起去爬山。", "by": "柏翰", "votes": 38, "at": "2026-10-22T15:21:40Z" }
  ]
}
欄位說明
id繪馬的 id
text、by願望（最多 40 字）、署名（最多 12 字）
votes這塊繪馬目前的祈願數（所有人的）
image繪馬背面的照片網址（/v1/wishes 才有；沒有附圖是 null）。照片只能從網站上傳，API 不收檔案
at掛上或祈願的時間（UTC）

錯誤（所有端點共用）

狀態碼error意思與處理
401missing_token沒帶 Authorization 標頭。登入後帶上權杖再試
401invalid_token權杖是假的或已經過期。重新登入拿新的權杖
400invalid_text、invalid_by、invalid_json、invalid_before（before 不是上一頁的 next）輸入不符合規定，看 message 怎麼改
404not_found沒有這塊繪馬，或沒有這個端點
405method_not_allowed（/me）只接受 GET
409already_prayed已經為這塊繪馬祈願過
429rate_limited10 分鐘內掛太多塊，等一下再試
500server_error 等伺服器的問題，稍後再試（細節只記在後台，不會回給你）

回應如果是 {"code":"UNAUTHORIZED_…"} 這種格式，代表請求在 Supabase 的閘道就被擋下，還沒進到這支 API 的程式。通常是後台的「Verify JWT with legacy secret」還開著。

試呼叫

在這個網站登入之後，可以直接在這裡呼叫 /me，比較帶與不帶權杖的差別。結果只顯示在你自己的畫面上。

還沒開放