> ## 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 事件** - 如需觸發 Webhook，請使用單筆建立訂單 API ### 限制 - 每次請求最多 **100 筆** - 採用部分成功策略 ### 冪等處理 - `order_no` 已存在時，只更新**非空欄位** - 不會覆蓋現有值，而是累積更新 ## OpenAPI ````yaml /api-reference/openapi.yaml post /orders/batch 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/batch: post: tags: - Orders summary: 批次匯入訂單 description: | 批次建立多筆訂單，適合匯入歷史資料。 ### ⚠️ 重要提醒 - **批次匯入不會觸發 Webhook 事件** - 如需觸發 Webhook，請使用單筆建立訂單 API ### 限制 - 每次請求最多 **100 筆** - 採用部分成功策略 ### 冪等處理 - `order_no` 已存在時，只更新**非空欄位** - 不會覆蓋現有值，而是累積更新 operationId: batchCreateOrders requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchOrderRequest' example: orders: - order_no: ORD-001 amount: '990.00' status: paid customer_email: user1@example.com currency: TWD payment_method: credit_card billing_cycle: monthly paid_at: '2026-01-01T00:00:00Z' - order_no: ORD-002 amount: '1990.00' status: paid customer_email: user2@example.com currency: TWD payment_method: atm billing_cycle: yearly paid_at: '2026-01-05T10:30:00Z' - order_no: ORD-003 amount: '599.00' status: paid customer_email: user3@example.com currency: TWD payment_method: line_pay billing_cycle: monthly paid_at: '2026-01-10T08:00:00Z' - order_no: ORD-004 amount: '3500.00' status: paid customer_email: user4@example.com currency: TWD payment_method: cvs billing_cycle: one-time paid_at: '2026-01-12T16:45:00Z' responses: '200': description: 批次匯入結果 content: application/json: schema: $ref: '#/components/schemas/BatchImportResponse' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationError' components: schemas: BatchOrderRequest: type: object required: - orders properties: on_conflict: type: string enum: - skip - update default: update description: | order_no 衝突時的處理策略： - `skip`：跳過已存在的訂單 - `update`（預設）：更新非空欄位（冪等處理） orders: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/CreateOrderRequest' BatchImportResponse: type: object properties: data: type: object properties: total: type: integer description: 總筆數 created: type: integer description: 新建成功數 updated: type: integer description: 更新成功數 skipped: type: integer description: 跳過數 failed: type: integer description: 失敗數 results: type: object properties: created: type: array items: $ref: '#/components/schemas/BatchResultItem' updated: type: array items: $ref: '#/components/schemas/BatchResultItem' skipped: type: array items: $ref: '#/components/schemas/BatchSkippedItem' failed: type: array items: $ref: '#/components/schemas/BatchFailedItem' 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: 自訂欄位 BatchResultItem: type: object properties: index: type: integer description: 原始陣列索引 id: type: integer description: 建立/更新的資源 ID identifier: type: string description: 識別碼（email 或 order_no） BatchSkippedItem: type: object properties: index: type: integer reason: type: string description: 跳過原因 example: duplicate_email identifier: type: string BatchFailedItem: type: object properties: index: type: integer reason: type: string description: 失敗原因 example: validation_error message: type: string description: 錯誤訊息 identifier: type: string 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 設定」頁面取得。 ````