> ## 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.

# 批次匯入訂閱

> 批次建立多筆訂閱。

### 來源優先順序
- `api` > `inferred`
- API 來源的訂閱可覆蓋系統推導的訂閱




## OpenAPI

````yaml /api-reference/openapi.yaml post /subscriptions/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:
  /subscriptions/batch:
    post:
      tags:
        - Subscriptions
      summary: 批次匯入訂閱
      description: |
        批次建立多筆訂閱。

        ### 來源優先順序
        - `api` > `inferred`
        - API 來源的訂閱可覆蓋系統推導的訂閱
      operationId: batchCreateSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSubscriptionRequest'
      responses:
        '200':
          description: 批次匯入結果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchImportResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    BatchSubscriptionRequest:
      type: object
      required:
        - subscriptions
      properties:
        on_conflict:
          type: string
          enum:
            - skip
            - update
          default: skip
        subscriptions:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/CreateSubscriptionRequest'
    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'
    CreateSubscriptionRequest:
      type: object
      required:
        - customer_id
        - mrr
        - billing_cycle
        - started_at
        - current_period_start
      properties:
        customer_id:
          type: integer
          description: 客戶 ID
        plan_name:
          type: string
          description: 方案名稱
          example: Pro Plan
        mrr:
          type: string
          description: 月經常性收入
          example: '990.00'
        billing_cycle:
          type: string
          enum:
            - monthly
            - quarterly
            - semi-annual
            - yearly
          description: 訂閱週期
        started_at:
          type: string
          format: date-time
          description: 訂閱開始時間
        current_period_start:
          type: string
          format: date-time
          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 設定」頁面取得。

````