openapi: 3.0.3
info:
  title: TI store 库存和价格 API
  description: 这些 API 用于检索 TI store 目录信息，包括价格（适用于 TI.com 上所有可用货币）、现货库存和订单限制。请参阅<a href="https://e2e.ti.com/search?q=error inventory&category=forum&group=453_452&faq=true&sort=date%20asc">错误代码和详细说明</a>的完整列表。
  version: 2.0.0
  contact:
    name: API 支持
    url: https://api-portal.ti.com/support
servers:
  - url: 'https://transact.ti.com/v2'
    description: 外部生产 API 网关

security:
  - OAuth2: []
tags:
  - name: 产品库存
paths:
  '/store/products/{tiPartNumber}':
    parameters:
      - name: tiPartNumber
        in: path
        description: >-
          产品的 URL 编码唯一标识符（可订购器件型号）。注意：在进行 API 调用之前，必须对包含 /NOPB 的器件型号进行编码，否则响应将是&ldquo;not found&rdquo;错误。例如，LP2982AIM5-3.3/NOPB 必须编码为 LP2982AIM5-3.3%2FNOPB。确保编码过程没有换行符，例如 LP2989IM-2.5%2FNOPB%0A%0A，因为这也会导致产品&ldquo;not found&rdquo;错误。
        required: true
        schema:
          type: string
          example: AFE7799IABJ
    get:
      description: >-
        按 OPN（可订购器件型号）获取特定产品的信息
      tags:
        - Product inventory
      operationId: getProductInformation
      security:
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/currencyParameter'
        - $ref: '#/components/parameters/excludeEVMsParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/products':
    get:
      description: >-
        获取 TI store 产品分页列表
      tags:
        - Product inventory
      operationId: getProductList
      security:
        - OAuth2: []
      parameters:
        - name: gpn
          in: query
          description: >-
            一个或多个子产品的通用器件型号（也称为基础器件型号）。
          required: true
          schema:
            type: string
            example: AFE7799
        - $ref: '#/components/parameters/currencyParameter'
        - $ref: '#/components/parameters/excludeEVMsParameter'
        - $ref: '#/components/parameters/pageParameter'
        - $ref: '#/components/parameters/sizeParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPage'
        '400':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/products/catalog':
    get:
      description: >-
        检索可从 TI store 购买的器件的完整目录。
      tags:
        - Product inventory
      operationId: getProductCatalog
      security:
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/currencyParameter'
        - $ref: '#/components/parameters/excludeEVMsParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCatalog'
        '400':
          $ref: '#/components/responses/UnprocessableEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    OAuth2:
      type: 'oauth2'
      description: >-
        此 API 将 OAuth 2 与客户端凭据结合使用。请参阅 https://api-portal.ti.com/order-api-authentication
      flows:
        clientCredentials:
          refreshUrl: 'https://transact.ti.com/v1/oauth'
          tokenUrl : 'https://transact.ti.com/v1/oauth'
          scopes: {}
  parameters:
    currencyParameter:
      name: currency
      in: query
      description: >-
        价格信息的特定币种。使用 ISO 4217 字母代码指定币种。如果未指定，则会提供以美元为单位的价格。
      required: false
      schema:
        type: string
        default: "USD"
        example: "USD"
    excludeEVMsParameter:
      name: exclude-evms
      in: query
      description: >-
        此标志用于从结果中排除 EVM（评估模块）产品。如果未指定，则会包含 EVM。
      required: false
      schema:
        type: boolean
        default: false
        example: true
    pageParameter:
      name: page
      in: query
      description: >-
        要从此请求返回的页面索引（从 0 开始）
      required: true
      schema:
        type: integer
        format: int32
        default: 0
        example: 0
    sizeParameter:
      name: size
      in: query
      description: >-
        要返回的页面大小（1 到 100 之间）
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
        example: 20
  responses:
    UnprocessableEntity:
      description: 422 无法处理的实体
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1001
                type: Validation
                section: QueryParameter
                field: page
                reason: Invalid page
                message: "page must be greater than or equal to 0"
              - errorCode: ERR-TICOM-INV-API-1001
                type: Validation
                section: QueryParameter
                field: size
                reason: Invalid size
                message: "size must be between 1 and 100"
    Unauthorized:
      description: 401 未经授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1004
                type: Security
                reason: "Invalid Credentials"
                message: "Provide a valid Bearer token"
    Forbidden:
      description: 403 禁止
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1004
                type: Security
                reason: "Invalid Credentials"
                message: "Provide a valid Bearer token"
    NotFound:
      description: 404 未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: ERR-TICOM-INV-API-1002
                type: ResourceNotFound
                section: Path
                field: tiPartNumber
                reason: "Resource could not be found"
                message: "Product not found for 'DOESNOTEXIST'"
    MethodNotAllowed:
      description: 405 方法不被允许
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00356
                type: Validation
                reason: Invalid method
                message: "PATCH is not a supported method."
    TooManyRequests:
      description: 429 请求太多
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00235
                type: Security
                reason: Too many requests
                message: Rate Limit Quota Hit.
    InternalServerError:
      description: 500 内部服务器错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - errorCode: TI-API-00556
                type: Unknown
                reason: Service unavailable
                message: This service is temporarily unavailable. Please contact support.
  schemas:
    Error:
      title: 错误
      description: >-
        标准错误响应
      type: object
      properties:
        errors:
          type: array
          description: >-
            错误消息
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: >-
                  已返回错误的唯一代码。
                example: "ERR-TICOM-INV-API-1001"
              type:
                type: string
                description: >-
                  错误的分类。
                example: Validation
              section:
                type: string
                description: >-
                  主要用于验证错误。提供请求中可以找到违规字段的部分。
                example: "InventorySubscription"
              field:
                type: string
                description: >-
                  验证失败的字段的名称（如果适用）。
                example: "tiPartNumber"
              reason:
                type: string
                description: >-
                  产生错误的原因。详细说明请求被拒绝的原因。
                example: >-
                  Invalid tiPartNumber.
              message:
                type: string
                description: >-
                  具体错误的详细信息以及要采取的解决措施。对于验证错误，这将包含无效值以及限制等详细信息。
                example: >-
                  tiPartNumber 'DOESNOTEXIST' is not a valid product. Please provide a valid tiPartNumber.
    FutureInventory:
      type: object
      properties:
        forecastQuantity:
          type: integer
          description: >-
            可用的估计库存数量。如果估计数量未知，则该值可为 null。
          format: int32
        forecastDate:
          type: string
          description: >-
            预计可用的日期（UTC，YYYY-MM-DD）。
          example: "2023-10-11"
          format: date
    Product:
      title: 产品
      description: 产品属性
      type: object
      properties:
        tiPartNumber:
          type: string
          description: >-
            产品的唯一标识符（可订购器件型号）。
          example: "AFE7799IABJ"
        genericPartNumber:
          type: string
          description: >-
            产品的通用器件型号（也称为基础器件型号）。
          example: "AFE7799"
        buyNowUrl:
          type: string
          description: >-
            用于在 TI store 中购买产品的 URL。
          example: "https://www.ti.com/product/AFE7799/part-details/AFE7799IABJ"
        quantity:
          type: integer
          description: >-
            TI store 中当前可出售的库存数量。
          format: int32
          example: 5435
        limit:
          type: integer
          description: >-
            TI.com 商店中的订单限制（如果存在限制）。
          example: 50
        pricing:
          type: array
          description: >-
            按币种进行价格分级的信息。
          items:
            $ref: '#/components/schemas/Pricing'
        futureInventory:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/FutureInventory'
          example:
            - forecastQuantity: 3500
              forecastDate: "2023-06-04"
            - forecastQuantity: 5000
              forecastDate: "2023-06-11"
            - forecastQuantity: 2000
              forecastDate: "2023-06-18"
        description:
          type: string
          description: >-
            产品的描述
          example: "8-Bit 200MSPS Low-Power Analog-to-Digital Converter (ADC) With Internal Sample and Hold"
        minimumOrderQuantity:
          type: integer
          description: >-
            TI store 的产品最低起订量 (MOQ)
          format: int32
          example: 1
        standardPackQuantity:
          type: integer
          description: >-
            产品的标准包装数量 (SPQ)
          format: int32
          example: 126
        exportControlClassificationNumber:
          type: string
          description: >-
            产品的出口管制分类编号 (ECCN)
          example: "EAR99"
        htsCode:
          type: string
          description: >-
            产品的 10 位协调关税表代码
          example: "8542390001"
        pinCount:
          type: integer
          description: >-
            产品的引脚数
          format: int32
          example: 5
        packageType:
          type: string
          description: >-
            产品的封装类型
          example: "SOT-23 (DBV)"
        packageCarrier:
          type: string
          description: >-
            产品的包装类型
          example: "Large T&R"
        customReel:
          type: boolean
          description: >-
            指示是否提供定制卷带包装。
          example: true
        lifeCycle:
          type: string
          description: >-
            产品生命周期状态
          example: "ACTIVE"
    Pricing:
      title: 价格
      description: 按数量进行的价格分级
      type: object
      properties:
        currency:
          type: string
          description: >-
            价格币种 ISO 4217 代码
          example: "USD"
        priceBreaks:
          type: array
          description: >-
            价格分级
          items:
            type: object
            properties:
              priceBreakQuantity:
                type: integer
                description: >-
                  价格分级数量
                format: int32
              price:
                type: number
                description: >-
                  价格分级数量的对应价格
          example:
            - priceBreakQuantity: 1
              price: 2.03
            - priceBreakQuantity: 10
              price: 1.43
            - priceBreakQuantity: 25
              price: 1.35
            - priceBreakQuantity: 100
              price: 1.10
            - priceBreakQuantity: 200
              price: 1.00
            - priceBreakQuantity: 350
              price: 0.95
            - priceBreakQuantity: 600
              price: 0.90
            - priceBreakQuantity: 750
              price: 0.85
    ProductCatalog:
      title: ProductCatalog
      description: >-
        可订购器件型号的完整列表。
      type: object
      properties:
        catalog:
          type: array
          description: 器件列表
          items:
            $ref: '#/components/schemas/Product'
    ProductPage:
      title: Page<Product>
      description: >-
        可分页产品列表响应
      type: object
      properties:
        content:
          type: array
          description: >-
            所请求页面中的产品列表
          items:
            $ref: '#/components/schemas/Product'
        first:
          type: boolean
          description: >-
            指示返回的页面是否是匹配结果集的第一页
          example: true
        last:
          type: boolean
          description: >-
            指示返回的页面是否是匹配结果集的最后一页
          example: false
        number:
          type: integer
          description: >-
            返回的页码。此值将与请求中指定的 Page 请求参数匹配。
          format: int32
          example: 0
        numberOfElements:
          type: integer
          description: >-
            当前页面中元素的数量
          format: int32
          example: 1
        size:
          type: integer
          description: >-
            页面的大小。此值将与请求中指定的 Size 请求参数匹配。
          format: int32
          example: 10
        totalElements:
          type: integer
          description: >-
            结果集内的产品总数（不限于当前页面）
          format: int64
          example: 1
        totalPages:
          type: integer
          description: >-
            结果集内的总页数（基于页面大小）
          format: int32
          example: 1
