接口索引¶

PAYMENT 接入相關 HTTP 接口一覽。路徑參數名與 FastAPI 宣告一致（coverage 測試比對此表）。

Farm Bearer 規則（以 server/main.py 為準，不臆測外層 proxy）：

範圍	`Authorization: Bearer <api_key>`
Connectivity：`GET /health`、`GET /ready`	不需（無 `require_tenant`）
Field：`POST /v1/enrollments/redeem`	不需（token 即憑證）
其餘本表 PAYMENT `/v1` 入口	需要；缺／無效 → 401

跨 tenant → 404。

Connectivity¶

Method	Path	說明	文件
`GET`	`/health`	Process liveness；無 Farm Bearer	getting-started
`GET`	`/ready`	MQ + DB smoke；失敗 503；無 Farm Bearer	getting-started

Method	Path	說明	文件
`POST`	`/v1/enrollments`	建 enrollment；token 只回一次	enrollment
`GET`	`/v1/enrollments/{enrollment_id}`	權威 enrollment 狀態	enrollment
`POST`	`/v1/enrollments/redeem`	Field／FarmAgent；token 即憑證，無 Farm Bearer	enrollment

Method	Path	說明	文件
`GET`	`/v1/devices`	本 tenant 裝置列表（Payment DTO）	devices
`GET`	`/v1/devices/{device_id}`	單裝置：online／WDA／lock／banks	devices
`PUT`	`/v1/devices/{device_code}/banks/{bank_code}/secret`	寫入／更新 PIN（可選 variant）	devices
`DELETE`	`/v1/devices/{device_code}/banks/{bank_code}`	解綁銀行（204）	devices
`POST`	`/v1/devices/{device_code}/unlock`	generation 安全解鎖	devices

Method	Path	說明	文件
`POST`	`/v1/tasks`	入列 balance／transaction_pull／transfer／transfer_verify	tasks
`GET`	`/v1/tasks/{task_id}`	權威 task 狀態	tasks
`GET`	`/v1/tasks`	`?idempotency_key=` 反查原單	tasks
`POST`	`/v1/transaction-pull/recovery`	等價 recovery 模式 transaction_pull	tasks

路徑	原因
`POST /v1/heartbeat`	Agent-only
`/v1/agent/*`	Agent-only
`/admin/*`	Ops／Admin
`/v1/mock/*`	僅 `ENABLE_MOCK_CALLBACK=1` 測試 sink；非正式 PAYMENT surface

非「PAYMENT 呼叫的 HTTP 接口」，契約見 callbacks：