openapi: 3.0.3
info:
  title: TI store 库存订阅 API
  description: 此 API 支持用户订阅库存补货通知。当器件库存充足时，此 API 将生成一个通知，而该通知将通过 HTTP POST 请求发送至您配置的 API。
  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: 库存订阅（测试）
  - name: 库存订阅
paths:
  '/store/subscriptions/inventory/test':
    post:
      tags:
        - Inventory subscriptions (test)
      security:
        - OAuth2: [] 
      description: >-
        触发向系统发送测试通知。此 API 将根据规范生成一条模拟通知并通过 HTTP POST 请求发送至您配置的 API。然后，它将返回从您的 API 返回的状态代码，如果不成功，则通过&ldquo;消息&rdquo;返回响应正文（如果有）
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryNotificationTestResponse'
              examples:
                successful:
                  value:
                    status: accepted
                failed:
                  value:
                    status: failed
                    responseCode: 401
                    message: "{\"Error\": \"Something went wrong\"}"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/subscriptions/inventory':
    get:
      description: >-
        获取所有有效订阅
      tags:
        - Inventory subscriptions
      operationId: getSubscriptionList
      security:
        - OAuth2: [] 
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySubscription'
              example:
                - tiPartNumber: "AFE7799IABJ"
                  requestedQty: 1000
                  currency: "USD"
                  autoSubscribe: true
                  expiration: 30
                  expirationDate: "2022-07-29"
                  creationTs: "2022-06-29T03:34:25+0000"
                  lastUpdatedTs: "2022-06-29T03:34:25+0000"
                - tiPartNumber: "OPA333AID"
                  requestedQty: 2500
                  currency: "CNY"
                  autoSubscribe: true
                  expiration: 30
                  expirationDate: "2022-07-30"
                  creationTs: "2022-06-30T03:34:25+0000"
                  lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      description: >-
        创建/更新订阅
      tags:
        - Inventory subscriptions
      operationId: upsertSubscription
      security:
        - OAuth2: [] 
      requestBody:
        description: >-
          要创建或更新的订阅。如果请求的 OPN 存在有效订阅，则订阅将更新为新的到期日期和新的请求数量。如果请求的 OPN 不存在有效订阅，则会根据规范创建新订阅。
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventorySubscription'
            examples:
              AFE7799IABJ:
                value:
                  tiPartNumber: "AFE7799IABJ"
                  requestedQty: 1000
                  currency: "USD"
                  autoSubscribe: true
                  expiration: 30
              OPA333AID:
                value:
                  tiPartNumber: "OPA333AID"
                  requestedQty: 2500
                  currency: "CNY"
                  autoSubscribe: true
                  expiration: 30
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySubscription'
              examples:
                AFE7799IABJ:
                  value:
                    tiPartNumber: "AFE7799IABJ"
                    requestedQty: 1000
                    currency: "USD"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-29"
                    creationTs: "2022-06-29T03:34:25+0000"
                    lastUpdatedTs: "2022-06-29T03:34:25+0000"
                OPA333AID:
                  value:
                    tiPartNumber: "OPA333AID"
                    requestedQty: 2500
                    currency: "CNY"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-30"
                    creationTs: "2022-06-30T03:34:25+0000"
                    lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      callbacks:
        inventoryStockupEvent:
          '${companyProfile.inventoryAPI}':
            post:
              summary: >-
                Inventory Notification of stockup for subscribed part
              tags:
                - InventoryNotification
              description: >-
                发送至您的 API 以告知备货情况的库存备货通知规范
              security:
                - Basic: []
                - ApiKey: []
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/InventoryNotification'
              responses:
                '200':
                  description: >-
                    确认收到库存通知
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/InventoryNotificationResponse'
    delete:
      description: >-
        删除公司资料的所有订阅。
      tags:
        - Inventory subscriptions
      security:
        - OAuth2: [] 
      responses:
        '204':
          description: >-
            无内容 - 成功响应
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  '/store/subscriptions/inventory/{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: >-
        获取公司资料的与指定产品标识符匹配的单个有效库存订阅
      tags:
        - Inventory subscriptions
      operationId: getSubscriptionByProductId
      security:
        - OAuth2: [] 
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySubscription'
              examples:
                AFE7799IABJ:
                  value:
                    tiPartNumber: "AFE7799IABJ"
                    requestedQty: 1000
                    currency: "USD"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-29"
                    creationTs: "2022-06-29T03:34:25+0000"
                    lastUpdatedTs: "2022-06-29T03:34:25+0000"
                OPA333AID:
                  value:
                    tiPartNumber: "OPA333AID"
                    requestedQty: 2500
                    currency: "CNY"
                    autoSubscribe: true
                    expiration: 30
                    expirationDate: "2022-07-30"
                    creationTs: "2022-06-30T03:34:25+0000"
                    lastUpdatedTs: "2022-06-30T03:34:25+0000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: >-
        删除公司资料的单个有效库存订阅。
      tags:
        - Inventory subscriptions
      security:
        - OAuth2: [] 
      responses:
        '204':
          description: >-
            无内容 - 成功响应
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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: InventorySubscription
                field: tiPartNumber
                reason: Invalid tiPartNumber
                message: "tiPartNumber 'DOESNOTEXIST' is not a valid product. Please provide a valid tiPartNumber."
              - errorCode: ERR-TICOM-INV-API-1001
                type: Validation
                section: InventorySubscription
                field: currency
                reason: Invalid currency
                message: "currency 'DOESNOTEXIST' is not a valid currency. Please provide a valid currency."
    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.
    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'
        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
    InventorySubscription:
      title: 库存订阅
      description: >-
        订阅缺货产品。有效订阅将触发向公司资料中配置的 API 发送库存通知。
      type: object
      properties:
        tiPartNumber:
          type: string
          description: >-
            此订阅适用的产品（可订购器件型号）的唯一标识符。
          example: "AFE7799IABJ"
        requestedQty:
          type: integer
          format: int32
          description: >-
            此订阅的库存数量。定义应触发库存通知的下限。例如，如果 RequestedQty = 1000，则所请求的产品从 0 到 500 的补货不会触发通知；但是，从 0 到 1500 的补货会向您的 API 触发库存通知。
          example: 1000
        currency:
          type: string
          description: >-
            要在库存通知提供的价格中使用的特定币种。使用 ISO 4217 字母代码指定币种。如果未指定，则会提供以美元为单位的价格。
          example: "USD"
        autoSubscribe:
          type: boolean
          default: true
          description: >-
            用于启用/禁用订阅自动续订的标志。默认情况下，发送库存通知后，订阅将被删除。但是，如果 AutoSubscribe 为 true，则该订阅将保持有效，直至其到达到期日期或被您删除。
          example: true
        expiration:
          type: integer
          format: int32
          default: 30
          description: >-
            订阅的持续时间（以天为单位）。这定义了订阅的期限，一旦达到指定的天数，就必须创建新订阅。
          minimum: 1
          maximum: 30
          example: 30
        expirationDate:
          type: string
          format: date
          description: >-
            此订阅的到期日期，格式为 YYYY-MM-DD
          readOnly: true
          example: "2022-06-29"
        creationTs:
          type: string
          format: date-time
          description: >-
            创建此订阅的时间戳，格式为 YYYY-MM-DD&apos;T&apos;HH24:mm:ss+ZZZZ
          readOnly: true
          example: "2022-06-29T03:34:25+0000"
        lastUpdatedTs:
          type: string
          format: date-time
          description: >-
            上次更新此订阅的时间戳，格式为 YYYY-MM-DD&apos;T&apos;HH24:mm:ss+ZZZZ
          readOnly: true
          example: "2022-06-29T03:34:25+0000"
    InventoryNotification:
      title: 库存通知
      description: 当发生订阅产品满足 requestedQty 的库存备货事件时向 API 发送通知。
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: >-
            通知的类型。对于库存订阅，来自这些订阅的通知被归类为&ldquo;库存&rdquo;
          example: "inventory"
        data:
          $ref: '#/components/schemas/Product'
    InventoryNotificationResponse:
      title: 库存通知响应
      description: "对库存通知的标准响应 - 确认成功接收"
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: >-
            通知接收状态。标准成功响应应为&ldquo;已接受&rdquo;
          default: "accepted"
          example: "accepted"
    InventoryNotificationTestResponse:
      title: 库存通知测试响应
      description: >-
        通知测试的扩展响应，其中包括连接测试的响应代码和响应消息。
      allOf:
        - $ref: '#/components/schemas/InventoryNotificationResponse'
        - type: object
          properties:
            responseCode:
              type: integer
              format: int32
              description: >-
                API 接收的响应的 HTTP 状态代码。主要用于不成功响应以及用于调试连接。对于 IO 错误和无法接收任何响应的情况，将返回 0。
              example: 401
            message:
              type: string
              description: >-
                从 API 返回的消息（如果适用）。主要用于不成功响应以及用于调试连接
              example: "{\"Error\": \"Something went wrong\"}"