> ## Documentation Index > Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt > Use this file to discover all available pages before exploring further. # 建立訂單 > 建立單一訂單。 ### Webhook 觸發 - 建立成功時觸發 `order.created` 事件 - 若 status 為 `paid`，同時觸發 `order.paid` 事件 ### 時間戳記自動填入 若建立訂單時指定了 `status` 但未提供對應的時間欄位，系統會自動填入當前時間： - `status: paid` → 自動填入 `paid_at` - `status: refunded` → 自動填入 `refunded_at` - `status: failed` → 自動填入 `failed_at` 如果你已提供時間欄位（例如匯入歷史資料時），系統不會覆蓋你提供的值。 ### 冪等處理 可透過 `X-Idempotency-Key` header 實現冪等，重複請求會回傳相同結果。 ## OpenAPI ````yaml /api-reference/openapi.yaml post /orders openapi: 3.0.3 info: title: 帳獸 Zangsho API description: | 帳獸（Zangsho）是一個專為亞洲電商與 SaaS 企業設計的營收分析平台。 ## 🔐 認證 使用 **Bearer Token** 進行 API 認證。Token 可在商家後台的「API 設定」頁面取得。 ```bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ https://api.zangsho.com/v1/customers ``` ## ⏱️ 頻率限制 | 限制類型 | 額度 | 說明 | |---------|------|------| | 已認證請求 | 3,600 次/小時 | 依商家 ID 計算 | | 未認證請求 | 10 次/分鐘 | 依 IP 計算 | 每個回應都包含以下 headers： - `X-RateLimit-Limit`: 限制額度 - `X-RateLimit-Remaining`: 剩餘次數 - `X-RateLimit-Reset`: 重置時間 (Unix timestamp) ## 📦 批次匯入 - 每次請求最多 **100 筆** - 採用**部分成功策略**（不全部回滾） - 回傳 `created`/`updated`/`skipped`/`failed` 詳細結果 - ⚠️ **批次匯入不觸發 Webhook**（僅記錄 Activity Log），如需觸發 Webhook 請使用單筆 API ## 🕐 時間格式 所有時間欄位使用 **ISO 8601 格式（UTC）**，例如：`2026-01-09T08:00:00Z` 商家需自行將本地時間轉換為 UTC 後傳入。 version: 1.0.0 contact: name: Zangsho Support email: support@zangsho.com x-logo: url: https://zangsho.com/logo.png altText: 帳獸 Zangsho Logo servers: - url: https://api.zangsho.com/v1 description: Production - url: http://zangsho.test:81/api/v1 description: Development security: - bearerAuth: [] tags: - name: Customers description: | 客戶管理 API 客戶是所有分析的基礎，包含 LTV（客戶終身價值）、訂單歷史等資訊。 - name: Orders description: | 訂單管理 API 訂單是營收分析的核心，支援批次匯入歷史資料。 - name: Subscriptions description: | 訂閱管理 API 訂閱用於計算 MRR（月經常性收入）、Churn Rate 等 SaaS 指標。 - name: Subscription Events description: | 訂閱事件 API 記錄訂閱的升級、降級、取消等事件，用於分析客戶旅程。 paths: /orders: post: tags: - Orders summary: 建立訂單 description: | 建立單一訂單。 ### Webhook 觸發 - 建立成功時觸發 `order.created` 事件 - 若 status 為 `paid`，同時觸發 `order.paid` 事件 ### 時間戳記自動填入 若建立訂單時指定了 `status` 但未提供對應的時間欄位，系統會自動填入當前時間： - `status: paid` → 自動填入 `paid_at` - `status: refunded` → 自動填入 `refunded_at` - `status: failed` → 自動填入 `failed_at` 如果你已提供時間欄位（例如匯入歷史資料時），系統不會覆蓋你提供的值。 ### 冪等處理 可透過 `X-Idempotency-Key` header 實現冪等，重複請求會回傳相同結果。 operationId: createOrder parameters: - name: X-Idempotency-Key in: header schema: type: string description: 冪等鍵（24 小時內有效） example: unique-request-id-123 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' examples: 信用卡月繳訂單: summary: 信用卡月繳訂單 value: order_no: ORD-20260109-001 amount: '990.00' status: paid customer_email: customer@example.com customer_name: 王小明 currency: TWD payment_method: credit_card billing_cycle: monthly paid_at: '2026-01-09T08:00:00Z' ATM 轉帳一次性訂單: summary: ATM 轉帳一次性訂單 value: order_no: ORD-20260115-042 amount: '3500.00' status: paid customer_email: buyer@example.com customer_name: 李大華 currency: TWD payment_method: atm billing_cycle: one-time paid_at: '2026-01-15T14:30:00Z' LINE Pay 季繳訂單: summary: LINE Pay 季繳訂單 value: order_no: ORD-20260120-088 amount: '2490.00' status: paid customer_email: linepay-user@example.com customer_name: 張美美 currency: TWD payment_method: line_pay billing_cycle: quarterly paid_at: '2026-01-20T09:15:00Z' 超商繳費訂單: summary: 超商繳費訂單（待付款） value: order_no: ORD-20260122-103 amount: '599.00' status: pending customer_email: cvs-user@example.com customer_name: 陳志明 currency: TWD payment_method: cvs billing_cycle: monthly 街口支付年繳訂單: summary: 街口支付年繳訂單 value: order_no: ORD-20260201-055 amount: '9900.00' status: paid customer_email: jko-user@example.com customer_name: 林小安 currency: TWD payment_method: jkopay billing_cycle: yearly paid_at: '2026-02-01T11:00:00Z' USD 信用卡訂單: summary: 外幣（美元）信用卡訂單 value: order_no: ORD-20260205-INT-001 amount: '49.99' status: paid customer_email: intl-customer@example.com customer_name: John Chen currency: USD payment_method: credit_card billing_cycle: monthly paid_at: '2026-02-05T03:20:00Z' responses: '201': description: 訂單建立成功 content: application/json: schema: $ref: '#/components/schemas/OrderResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' components: schemas: CreateOrderRequest: type: object required: - order_no - amount - customer_email properties: order_no: type: string description: 訂單編號（商家內唯一） example: ORD-20260109-001 amount: type: string description: 訂單金額 example: '990.00' status: type: string enum: - pending - paid - failed - refunded - cancelled default: pending description: 訂單狀態 customer_email: type: string format: email description: 客戶 Email（不存在會自動建立客戶） customer_name: type: string description: 客戶姓名（建立新客戶時使用） currency: type: string default: TWD description: | 幣別，使用 ISO 4217 貨幣代碼。預設為 `TWD`（新台幣）。 常見幣別： | 代碼 | 說明 | |------|------| | `TWD` | 新台幣 | | `USD` | 美元 | | `JPY` | 日圓 | | `HKD` | 港幣 | | `SGD` | 新加坡幣 | | `CNY` | 人民幣 | | `KRW` | 韓元 | | `MYR` | 馬來西亞令吉 | | `THB` | 泰銖 | | `EUR` | 歐元 | | `GBP` | 英鎊 | example: TWD payment_method: type: string enum: - credit_card - atm - cvs - line_pay - jkopay - apple_pay description: | 付款方式。支援以下選項： | 值 | 說明 | |------|------| | `credit_card` | 信用卡 | | `atm` | ATM 轉帳 | | `cvs` | 超商繳費（代碼繳費） | | `line_pay` | LINE Pay | | `jkopay` | 街口支付 | | `apple_pay` | Apple Pay | example: credit_card billing_cycle: type: string enum: - monthly - quarterly - semi-annual - yearly - one-time description: 訂閱週期（影響 MRR 計算） paid_at: type: string format: date-time description: 付款時間（若未提供且 status 為 `paid`，系統自動填入當前時間） refunded_at: type: string format: date-time description: 退款時間（若未提供且 status 為 `refunded`，系統自動填入當前時間） failed_at: type: string format: date-time description: 付款失敗時間（若未提供且 status 為 `failed`，系統自動填入當前時間） metadata: type: object description: 自訂欄位 OrderResponse: type: object properties: data: $ref: '#/components/schemas/Order' Order: type: object properties: id: type: integer order_no: type: string amount: type: string currency: type: string description: 幣別（ISO 4217 貨幣代碼） example: TWD status: type: string enum: - pending - paid - failed - refunded - cancelled payment_method: type: string enum: - credit_card - atm - cvs - line_pay - jkopay - apple_pay description: 付款方式 nullable: true source: type: string enum: - api - import - manual - webhook billing_cycle: type: string paid_at: type: string format: date-time nullable: true refunded_at: type: string format: date-time nullable: true failed_at: type: string format: date-time nullable: true metadata: type: object nullable: true customer_email: type: string description: 客戶 Email（當客戶關聯載入時回傳） customer_name: type: string description: 客戶姓名（當客戶關聯載入時回傳） created_at: type: string format: date-time updated_at: type: string format: date-time responses: Unauthorized: description: 未認證或 Token 無效 content: application/json: schema: type: object properties: message: type: string example: Unauthenticated. ValidationError: description: 驗證錯誤 content: application/json: schema: type: object properties: message: type: string example: The given data was invalid. errors: type: object additionalProperties: type: array items: type: string example: message: The given data was invalid. errors: email: - The email field is required. - The email must be a valid email address. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Sanctum Token description: | 使用 Laravel Sanctum Token 進行認證。 Token 可在商家後台的「API 設定」頁面取得。 ````