跳轉到

五分鐘接入

Base URL

環境 Base URL
PRE 由對接窗口提供（placeholder：$FARM_BASE）
OL（Production） 由對接窗口提供；勿臆造 hostname

全文 curl 使用環境變數，不寫入真值：

export FARM_BASE="https://farm-pre.example"   # placeholder
export FARM_API_KEY="pay_xxx_placeholder"     # placeholder — 永不提交真實 key

鑑權

Connectivity 兩端點 不 需要 Farm Bearer（server/main.py 的 GET /health、GET /ready 無 require_tenant）：

端點 Farm Bearer
GET /health 不需
GET /ready 不需

其餘 PAYMENT /v1 入口（裝置、任務、enrollment 建立／查詢、recovery 等）皆需：

Authorization: Bearer $FARM_API_KEY

唯一 的 Field 例外：POST /v1/enrollments/redeem 以 token 即憑證， 無 Farm Bearer（Field／FarmAgent 呼叫）。

  • 需 Bearer 卻缺／無效 key → 401，並帶 WWW-Authenticate: Bearer
  • 跨 tenant 存取他人 device／task／enrollment → 404（不洩漏存在性）

本文件只描述 Farm API process 的鑑權契約，不臆測外層 proxy／Access 是否另有閘門。

/health 與 /ready

端點 意義 Farm Bearer
GET /health Process liveness。process 活著即可；不代表 MQ／DB ready 無
GET /ready 上游依賴 smoke：mq + db。皆 ok → 200 ready；否則 503 not_ready 無 
# 無 Authorization header
curl -sS "$FARM_BASE/health"
# → {"status":"ok","service":"farm-api","version":"…","git_commit":"…"}

curl -sS "$FARM_BASE/ready"
# → {"status":"ready","checks":{"mq":true,"db":true},"version":"…"}

Smoke：GET /v1/devices

curl -sS "$FARM_BASE/v1/devices" \
  -H "Authorization: Bearer $FARM_API_KEY"
# → {"devices":[…]}  本 tenant 裝置；Payment DTO（無 udid／agent 路由）

預期：

情況 結果
正確 key 200，devices 陣列（可為空）
缺／錯 key 401
錯誤 origin 的自訂 callback_url（後續 task） 400（origin 須與 tenant 預設 callback 相同）

Callback origin 限制

任務可帶 callback_url；其 origin（scheme + host + port） 必須與該 tenant 登記的 callback_url 相同，否則入列失敗 400。Worker 不跟隨 3xx（防 SSRF）。 未帶則使用 tenant 預設 callback。

下一步