openapi: 3.0.3
info:
  title: Honest FulPhilment (HF) User API v1 (Claude Connector)
  version: 1.0.0
  description: |
    Machine-readable user-side API for Claude / MCP connectors (Honest FulPhilment / HF).
    Auth via header `x-key` (AccessKey). Scopes gate each resource.
    Limits: 60 req/min per key (429), pageSize max 100, pay 10/min.
    Guide: https://honestfulphilment.com/ai-integration/ · Create keys: https://app.honestfulphilment.com/setting/access-key
servers:
  - url: https://api.honestfulphilment.com
    description: Production API host
security:
  - ApiKeyAuth: []
tags:
  - name: Orders
  - name: Inventory
  - name: Balance
  - name: Shipping
paths:
  /connector/v1/orders:
    get:
      tags: [Orders]
      operationId: listOrders
      summary: List merchant orders
      description: Requires scope `orders:read`.
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [ALL, NOT_PAID, NOT_HANDLE, SENDED, CANCEL, REFUND, PARTIALLY_PAID]
        - name: orderNo
          in: query
          schema: { type: string }
        - name: sku
          in: query
          schema: { type: string }
        - name: storeId
          in: query
          schema: { type: string }
        - name: startTime
          in: query
          schema: { type: string, format: date-time, example: "2026-08-01T00:00:00" }
        - name: endTime
          in: query
          schema: { type: string, format: date-time }
        - name: pageIndex
          in: query
          schema: { type: integer, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 10 }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseOrders"
  /connector/v1/orders/{id}:
    get:
      tags: [Orders]
      operationId: getOrder
      summary: Get order by id or orderNo
      description: Requires scope `orders:read`. Includes line items and address.
      parameters:
        - $ref: "#/components/parameters/IdOrOrderNo"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseOrder"
  /connector/v1/orders/{id}/pay:
    post:
      tags: [Orders]
      operationId: payOrder
      summary: Pay unpaid order with wallet balance
      description: |
        Requires scope `orders:pay` (not granted by default).
        Provide `idempotencyKey` for safe retries. Optional `confirmAmount` must match totalAmount.
      parameters:
        - $ref: "#/components/parameters/IdOrOrderNo"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [idempotencyKey]
              properties:
                idempotencyKey: { type: string }
                confirmAmount: { type: number }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponsePay"
  /connector/v1/inventory:
    get:
      tags: [Inventory]
      operationId: listInventory
      summary: List user inventory accounts
      description: Requires scope `inventory:read`. Use maxQuantity to find low-stock SKUs on the page.
      parameters:
        - name: keyword
          in: query
          schema: { type: string }
        - name: maxQuantity
          in: query
          schema: { type: integer }
        - name: warehouseCode
          in: query
          schema: { type: string, example: CN }
        - name: pageIndex
          in: query
          schema: { type: integer, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 10 }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseInventoryList"
  /connector/v1/inventory/{sku}:
    get:
      tags: [Inventory]
      operationId: getInventory
      summary: Get inventory by sku or id
      description: Requires scope `inventory:read`.
      parameters:
        - name: sku
          in: path
          required: true
          schema: { type: string }
        - name: includeLogs
          in: query
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseInventory"
  /connector/v1/balance:
    get:
      tags: [Balance]
      operationId: getBalance
      summary: Get wallet balance
      description: Requires scope `balance:read`.
      parameters:
        - name: includeRecentBilling
          in: query
          schema: { type: boolean, default: true }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseBalance"
  /connector/v1/billing:
    get:
      tags: [Balance]
      operationId: listBilling
      summary: List billing history
      description: Requires scope `balance:read`.
      parameters:
        - name: startTime
          in: query
          schema: { type: string, format: date-time }
        - name: endTime
          in: query
          schema: { type: string, format: date-time }
        - name: pageIndex
          in: query
          schema: { type: integer, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 10 }
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseBillingList"
  /connector/v1/shipping-rates:
    get:
      tags: [Shipping]
      operationId: listShippingRates
      summary: Quote shipping rates for SKUs
      description: |
        Requires scope `rates:read`. Weight is taken from catalog variants (do not pass weight).
        Prices are in USD, the same as the shipping calculator in the HF web app. `postCode` recommended for AU/CA.
      parameters:
        - name: countryCode
          in: query
          required: true
          schema: { type: string, example: US }
        - name: postCode
          in: query
          schema: { type: string, example: "10001" }
        - name: items
          in: query
          required: true
          schema: { type: string, example: "SKU1:2,SKU2:1" }
          description: Comma-separated SKU:quantity pairs; quantity defaults to 1
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseShippingRateList"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-key
  parameters:
    IdOrOrderNo:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: HF order id or order number (orderNo)
  schemas:
    ResponseEnvelope:
      type: object
      properties:
        status: { type: string, enum: [SUCCEED, FAILED] }
        errorCode: { type: string }
        errorMessage: { type: string }
        pageIndex: { type: integer }
        pageSize: { type: integer }
        totalCount: { type: integer }
        pageCount: { type: integer }
    ApiOrder:
      type: object
      properties:
        id: { type: string }
        orderNo: { type: string }
        storeId: { type: string }
        storeName: { type: string }
        status: { type: string, example: NOT_PAID }
        statusCode: { type: integer }
        shipmentNo: { type: string, description: Main / first-leg tracking number }
        transferNo: { type: string, description: Last-mile / final-leg tracking number when available; blank until assigned }
        shipmentMethodId: { type: string }
        shipmentMethodName: { type: string }
        countryCode: { type: string }
        productAmount: { type: number }
        shipmentAmount: { type: number }
        totalAmount: { type: number }
        currency: { type: string, example: USD }
        exchange: { type: number, description: FX snapshot used when amounts were priced }
        createTime: { type: string, format: date-time }
        items:
          type: array
          items:
            type: object
            properties:
              sku: { type: string }
              title: { type: string }
              quantity: { type: integer }
              price: { type: number }
              amount: { type: number }
    ApiInventory:
      type: object
      properties:
        id: { type: string }
        sku: { type: string }
        title: { type: string }
        quantity: { type: integer }
        alertThreshold: { type: integer }
        warehouseCode: { type: string }
    ApiBalance:
      type: object
      properties:
        balance: { type: number }
        currency: { type: string }
        recentBilling:
          type: array
          items:
            type: object
            properties:
              debit: { type: number }
              balance: { type: number }
              description: { type: string }
              orderNo: { type: string }
              createTime: { type: string, format: date-time }
    ApiPayResult:
      type: object
      properties:
        payId: { type: string }
        orderId: { type: string }
        orderNo: { type: string }
        totalAmount: { type: number }
        balanceAfter: { type: number }
        status: { type: string }
    ApiShippingRate:
      type: object
      properties:
        id: { type: string }
        name: { type: string, description: Carrier / service name }
        price: { type: number, description: Price in USD }
        currency: { type: string, example: USD }
        dayStart: { type: integer }
        dayEnd: { type: integer }
    ResponseOrders:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data:
              type: array
              items: { $ref: "#/components/schemas/ApiOrder" }
    ResponseOrder:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data: { $ref: "#/components/schemas/ApiOrder" }
    ResponseInventoryList:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data:
              type: array
              items: { $ref: "#/components/schemas/ApiInventory" }
    ResponseInventory:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data: { $ref: "#/components/schemas/ApiInventory" }
    ResponseBalance:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data: { $ref: "#/components/schemas/ApiBalance" }
    ResponseBillingList:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data:
              type: array
              items:
                type: object
    ResponseShippingRateList:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data:
              type: array
              items: { $ref: "#/components/schemas/ApiShippingRate" }
    ResponsePay:
      allOf:
        - $ref: "#/components/schemas/ResponseEnvelope"
        - type: object
          properties:
            data: { $ref: "#/components/schemas/ApiPayResult" }