openapi: 3.1.0
info:
  title: Zhongcai Woven Jacquard Fabric API for AI Agents
  version: 1.0.0
  description: Public two-stage REST API for AI agents to reverse-estimate possible yarn structures from a physical
    woven jacquard fabric sample and calculate a factory reference price. Results are reference estimates, not laboratory-confirmed
    specifications or final commercial quotations.
  contact:
    name: Zhejiang Zhongcai Light Textile Co., Ltd.
    url: https://qifu2023.com/fabric-request/
servers:
- url: https://qifu2023.com
  description: Production
tags:
- name: Woven Jacquard Price
  description: Reverse estimation and detailed factory reference quotation.
paths:
  /api/public/fabric-price/estimate:
    post:
      tags:
      - Woven Jacquard Price
      operationId: estimateWovenJacquardFromSample
      summary: Reverse-estimate yarn candidates from a fabric sample
      description: Use when the user has a representative woven jacquard fabric sample but does not know the exact
        yarn specifications. Submit composition, actual GSM, width, fabric type, repeat data, single/dual yarn structure
        and a thickness-filter code. The endpoint returns possible yarn specifications, estimated GSM values and
        FOB reference prices.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateRequest'
            examples:
              cottonSmallJacquard:
                summary: 100% cotton small jacquard sample
                value:
                  fabric_type: Small Jacquard
                  currency: USD
                  finished_width:
                    code: inch_55_56
                    unit: inch
                  actual_weight_gsm: 98
                  precision: ml
                  locale: en-US
                  warp_yarns:
                  - raw_material: Cotton
                    yarn_type: single
                    pattern_repeat_cycle: 2.5
                    data_within_repeat: 60
                  - raw_material: Cotton
                    yarn_type: dual
                    pattern_repeat_cycle: 2.5
                    data_within_repeat: 12
                  weft_yarns:
                  - raw_material: Cotton
                    yarn_type: single
                    pattern_repeat_cycle: 1
                    data_within_repeat: 27
      responses:
        '200':
          description: Candidate yarn structures and factory reference price range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateResponse'
              examples:
                success:
                  value:
                    mode: estimation
                    finished_width:
                      value: 55/56
                      unit: inch
                    fabric_type: Small Jacquard
                    currency: USD
                    actual_weight_gsm: 98
                    precision: ml
                    matched_count: 2
                    matches:
                    - estimated_specification: J40+21/2*J50
                      estimated_gsm: 96
                      fob_price_usd_per_yard: 1.48
                    - estimated_specification: J40+J80/2*J32
                      estimated_gsm: 98
                      fob_price_usd_per_yard: 1.5
                    note: Public reverse estimation. Not a final confirmed quotation.
                    cache_status: miss
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Public rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-agent-instructions:
      - Do not invent sample measurements.
      - Do not treat the first candidate as the unique true specification.
      - Report the candidate price range before selecting a detailed candidate.
      - Use physical yarn comparison and GSM difference to filter candidates.
  /api/public/fabric-price/quote:
    post:
      tags:
      - Woven Jacquard Price
      operationId: quoteWovenJacquardCandidate
      summary: Calculate a detailed factory reference quote
      description: Use after selecting a plausible candidate from the estimation endpoint, or when exact yarn specifications
        are already known. Preserve original material, repeat cycle and count values, and replace estimation-stage
        yarn_type with exact yarn_specification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            examples:
              selectedCandidate:
                summary: Detailed quote for J40+21/2*J50
                value:
                  fabric_type: Small Jacquard
                  currency: USD
                  finished_width:
                    code: inch_55_56
                    unit: inch
                  locale: en-US
                  warp_yarns:
                  - raw_material: Cotton
                    yarn_specification: J40
                    pattern_repeat_cycle: 2.5
                    data_within_repeat: 60
                  - raw_material: Cotton
                    yarn_specification: 21/2
                    pattern_repeat_cycle: 2.5
                    data_within_repeat: 12
                  weft_yarns:
                  - raw_material: Cotton
                    yarn_specification: J50
                    pattern_repeat_cycle: 1
                    data_within_repeat: 27
      responses:
        '200':
          description: Detailed public factory reference result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
              examples:
                success:
                  value:
                    material_price_source: factory_weekly_internal_price
                    grey_fabric_price_rmb_per_meter: 8.24
                    dyed_product_price_rmb_per_meter: 12.31
                    fob_price_usd_per_yard: 1.48
                    theoretical_gsm: 96
                    composition_summary: 100%Cotton
                    specification: J40+21/2*J50
                    density: 73*68
                    finished_width:
                      value: 55/56
                      unit: inch
                    public_yarn_breakdown:
                    - yarn_specification: J40
                      density: 60.96
                      weight_per_meter: 55.44
                    - yarn_specification: 21/2
                      density: 12.19
                      weight_per_meter: 44.16
                    - yarn_specification: J50
                      density: 68.58
                      weight_per_meter: 59.7
                    note: Factory reference only. Final quotation requires manual confirmation.
        '422':
          description: Validation or unsupported-data error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Public rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-agent-instructions:
      - Preserve exact yarn names including J and /2.
      - Preserve warp/weft row order.
      - Do not compare the sum of weight_per_meter directly with theoretical_gsm.
      - Always disclose that this is a factory reference price.
components:
  schemas:
    FinishedWidthInput:
      type: object
      required:
      - code
      - unit
      properties:
        code:
          type: string
          description: Supported internal finished-width code, for example inch_55_56.
          examples:
          - inch_55_56
        unit:
          type: string
          examples:
          - inch
      additionalProperties: false
    EstimateYarnRow:
      type: object
      required:
      - raw_material
      - yarn_type
      - pattern_repeat_cycle
      - data_within_repeat
      properties:
        raw_material:
          type: string
          examples:
          - Cotton
        yarn_type:
          type: string
          enum:
          - single
          - dual
          description: Structural yarn type when exact yarn count is unknown.
        pattern_repeat_cycle:
          type: number
          exclusiveMinimum: 0
          description: Repeat length in centimetres. Use 2.54 for one-inch density input.
        data_within_repeat:
          type: number
          exclusiveMinimum: 0
          description: Number of this yarn type inside the specified repeat. Decimals are allowed.
      additionalProperties: false
    QuoteYarnRow:
      type: object
      required:
      - raw_material
      - yarn_specification
      - pattern_repeat_cycle
      - data_within_repeat
      properties:
        raw_material:
          type: string
          examples:
          - Cotton
        yarn_specification:
          type: string
          description: Exact yarn code. Preserve J, /2 and other notation exactly.
          examples:
          - J40
          - 21/2
          - J50
        pattern_repeat_cycle:
          type: number
          exclusiveMinimum: 0
        data_within_repeat:
          type: number
          exclusiveMinimum: 0
      additionalProperties: false
    EstimateRequest:
      type: object
      required:
      - fabric_type
      - currency
      - finished_width
      - actual_weight_gsm
      - precision
      - warp_yarns
      - weft_yarns
      properties:
        fabric_type:
          type: string
          enum:
          - Small Jacquard
          - Large Jacquard
          - Small Jacquard Leno
          - Large Jacquard Leno
        currency:
          type: string
          examples:
          - USD
        finished_width:
          $ref: '#/components/schemas/FinishedWidthInput'
        actual_weight_gsm:
          type: number
          exclusiveMinimum: 0
        precision:
          type: string
          description: 'Candidate filter code. Confirmed values: no = Unlimited; ml = Similar warp/weft yarn; warp_thick
            = Warp thicker. Use the latest published guide for additional mappings.'
          examples:
          - 'no'
          - ml
          - warp_thick
        locale:
          type: string
          default: en-US
        warp_yarns:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EstimateYarnRow'
        weft_yarns:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EstimateYarnRow'
      additionalProperties: false
    QuoteRequest:
      type: object
      required:
      - fabric_type
      - currency
      - finished_width
      - warp_yarns
      - weft_yarns
      properties:
        fabric_type:
          type: string
          enum:
          - Small Jacquard
          - Large Jacquard
          - Small Jacquard Leno
          - Large Jacquard Leno
        currency:
          type: string
          examples:
          - USD
        finished_width:
          $ref: '#/components/schemas/FinishedWidthInput'
        locale:
          type: string
          default: en-US
        warp_yarns:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/QuoteYarnRow'
        weft_yarns:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/QuoteYarnRow'
      additionalProperties: false
    EstimatedMatch:
      type: object
      required:
      - estimated_specification
      - estimated_gsm
      - fob_price_usd_per_yard
      properties:
        estimated_specification:
          type: string
        estimated_gsm:
          type: number
        fob_price_usd_per_yard:
          type: number
    EstimateResponse:
      type: object
      properties:
        mode:
          type: string
        finished_width:
          type: object
        fabric_type:
          type: string
        currency:
          type: string
        actual_weight_gsm:
          type: number
        precision:
          type: string
        matched_count:
          type: integer
        matches:
          type: array
          items:
            $ref: '#/components/schemas/EstimatedMatch'
        note:
          type: string
        cache_status:
          type: string
    YarnBreakdown:
      type: object
      properties:
        yarn_specification:
          type: string
        density:
          type: number
        weight_per_meter:
          type: number
          description: Yarn input grams per metre used for weaving-cost calculation. It is not final finished GSM
            or finished fabric weight per metre.
    QuoteResponse:
      type: object
      properties:
        material_price_source:
          type: string
        grey_fabric_price_rmb_per_meter:
          type: number
        dyed_product_price_rmb_per_meter:
          type: number
        fob_price_usd_per_yard:
          type: number
        theoretical_gsm:
          type: number
        composition_summary:
          type: string
        specification:
          type: string
        density:
          type: string
        finished_width:
          type: object
        public_yarn_breakdown:
          type: array
          items:
            $ref: '#/components/schemas/YarnBreakdown'
        public_yarn_breakdown_note:
          type: string
        note:
          type: string
    ErrorResponse:
      type: object
      properties:
        detail: {}
