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

# 建立客戶

> 建立單一客戶。如果 email 已存在會回傳 422 錯誤。

若需要大量匯入客戶，請使用 [批次匯入客戶](#operation/batchCreateCustomers)。




## OpenAPI

````yaml /api-reference/openapi.yaml post /customers
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:
  /customers:
    post:
      tags:
        - Customers
      summary: 建立客戶
      description: |
        建立單一客戶。如果 email 已存在會回傳 422 錯誤。

        若需要大量匯入客戶，請使用 [批次匯入客戶](#operation/batchCreateCustomers)。
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            examples:
              basic:
                summary: 基本範例
                value:
                  email: customer@example.com
                  name: 王小明
              withMetadata:
                summary: 包含 metadata
                value:
                  email: customer@example.com
                  name: 王小明
                  phone: '0912345678'
                  metadata:
                    source: website
                    campaign: 2026-q1
      responses:
        '201':
          description: 客戶建立成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              example:
                data:
                  id: 123
                  email: customer@example.com
                  name: 王小明
                  phone: '0912345678'
                  metadata:
                    source: website
                  ltv: '0.00'
                  order_count: 0
                  first_payment_at: null
                  last_payment_at: null
                  created_at: '2026-01-09T08:00:00Z'
                  updated_at: '2026-01-09T08:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
components:
  schemas:
    CreateCustomerRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: 客戶 Email（商家內唯一）
          example: customer@example.com
        name:
          type: string
          description: 客戶姓名
          example: 王小明
        phone:
          type: string
          description: 電話號碼
          example: '0912345678'
        external_id:
          type: string
          description: 外部系統 ID（方便整合）
          example: cus_abc123
        metadata:
          type: object
          description: 自訂欄位（JSON 格式）
          example:
            source: website
            campaign: 2026-q1
    CustomerResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Customer'
    Customer:
      type: object
      properties:
        id:
          type: integer
          description: 客戶 ID
        email:
          type: string
          description: 客戶 Email
        name:
          type: string
          description: 客戶姓名
        phone:
          type: string
          description: 電話號碼
        external_id:
          type: string
          description: 外部系統 ID
        metadata:
          type: object
          description: 自訂欄位
        ltv:
          type: string
          description: 客戶終身價值（LTV）
          example: '29800.00'
        order_count:
          type: integer
          description: 成功訂單數
        first_payment_at:
          type: string
          format: date-time
          description: 首次付款時間
        last_payment_at:
          type: string
          format: date-time
          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.
    RateLimitError:
      description: 頻率限制超過
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: 每小時限制額度
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: 剩餘次數
        X-RateLimit-Reset:
          schema:
            type: integer
          description: 重置時間 (Unix timestamp)
        Retry-After:
          schema:
            type: integer
          description: 建議重試等待秒數
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Too Many Requests
              retry_after:
                type: integer
                example: 3600
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum Token
      description: |
        使用 Laravel Sanctum Token 進行認證。

        Token 可在商家後台的「API 設定」頁面取得。

````