openapi: 3.0.3
info: 
  title: 财务单据检索 API
  description: 此 API 支持用户检索财务发票信息。
  contact:
    name: API 支持
    url: https://api-portal.ti.com/support
  version: 2.0.0
servers:
  - url: 'https://transact.ti.com/v2'
    description: 外部生产 API 网关

security:
- OAuth2: []

tags:
- name: 财务单据（测试）
- name: 财务单据
paths: 
  /store/orders/{orderNumber}/financial-documents/{financialDocumentNumber}/test:
    get:
      description: "检索客户下达的给定销售订单号和供应商单据编号的测试财务单据详细信息。（为了进行测试，传递的 financialDocumentNumber 应始终为 - 5999999999）"
      tags: 
        - Financial document (test)
      security:
        - OAuth2: [] 
      parameters:
      - name: orderNumber
        in: path
        description: 供应商销售订单号
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: T10999999
      - name: financialDocumentNumber
        in: path
        description: 供应商单据编号
        required: true
        style: simple
        explode: false
        schema:
          type: string
          default: 5999999999
        example: 5999999999   
      - name: requestPDF
        in: query
        description: "如果在 RequestPDF 中传入 true 值，则响应将在字段 documentPDF 中包含 PDF 单据的 base64 编码字符串"
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          example: true
          enum:
          - true
          - false
          default: false
        example: true
      responses:
        '200':
          description: 已成功处理请求。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceRetrieveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'        
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotSupported'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'  
  /store/orders/{orderNumber}/financial-documents/{financialDocumentNumber}:
    get:
      description: 检索客户下达的给定销售订单号和供应商单据编号的财务单据详细信息。
      tags: 
        - Financial document
      security:
        - OAuth2: [] 
      parameters:
      - name: orderNumber
        in: path
        description: 供应商销售订单号
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: T10999999
      - name: financialDocumentNumber
        in: path
        description: TI 财务单据编号
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: 5999999999        
      - name: requestPDF
        in: query
        description: "如果在 RequestPDF 中传入 true 值，则响应将在字段 documentPDF 中包含 PDF 单据的 base64 编码字符串"
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          example: true
          enum:
          - true
          - false
          default: false
        example: true
      responses:
        '200':
          description: 已成功处理请求。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceRetrieveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'        
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotSupported'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'                        
components:
  responses:
    Okay:
      description: 正常响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceRetrieveResponse'
    BadRequest:
      description: 错误请求
      content:
        application/json:
          schema:
              example:
                errors:
                - errorCode: ERR-TICOM-FIR-API-0400
                  type: Validation
                  section: Path
                  message: The fields orderNumber, financialDocumentNumber cannot be null or empty.
                - errorCode: ERR-TICOM-FIR-API-0400
                  type: Validation
                  section: Path                
                  message: orderNumber - 87644567 must begin with 'T'.
                - errorCode: ERR-TICOM-ASNR-API-0400
                  type: Validation
                  section: Path 
                  message: orderNumber - T1234567 must be 9 characters in length.
                - errorCode: ERR-TICOM-FIR-API-0400
                  type: Validation
                  section: Path                
                  message: financialDocumentNumber - T04987431234 must be numeric.
                - errorCode: ERR-TICOM-FIR-API-0400
                  type: Validation
                  section: Path 
                  message: financialDocumentNumber - 65482544 must be 10 characters in length.   
                - errorCode: ERR-TICOM-FIR-API-0400
                  type: Validation
                  section: QueryParameter 
                  message: requestPDF - X must be true or false.                                            
    Unauthorized:
      description: 未经授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
            - errorCode: TI-API-0401
              type: Security
              reason: Invalid Credentials                
              message: "Your Access Token has Expired. Please refresh your token.\
                  \ For more information, please see: https://api-portal.ti.com/oauth-setup/"             
    NotFound:
      description: 未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:                    
            errors:
            - errorCode: TI-API-0404
              type: ResourceNotFound
              reason: Invalid path
              message: No API endpoint ('/order/T2345/financial-document/053434') found. See documentation of this API.
            - errorCode: ERR-TICOM-FIR-API-0404
              type: ResourceNotFound
              reason: Resource not found.
              message: Verify the orderNumber and financialDocumentNumber and resubmit the request.                           
    MethodNotSupported:
      description: 方法不受支持
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:                    
            errors:
            - errorCode: TI-API-0405
              type: ResourceNotFound
              reason: Invalid method
              message: POST is not a supported method. See documentation around this API at https://api-portal.ti.com/apis.              
    TooManyRequests:
      description: 请求太多
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:                    
            errors:
            - errorCode: TI-API-0429
              type: Security
              reason: Too many requests - Access Temporarily Restricted
              message: Rate Limit Quota exceeded. Please reduce the rate of requests. If issue persists, please contact support (https://api-portal.ti.com/support).               
    InternalServerError:
      description: 内部服务器错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:                
            errors:
            - errorCode: TI-API-0500
              type: Unknown
              reason: Backend System Error
              message: System error occurred, please contact support.
            - errorCode: ERR-TICOM-FIR-API-0500
              type: Unknown
              reason: Backend System Error
              message: "System error occurred, please contact support. Execution ID: execution-304816a1-a1e1-41e7-9214-59e872a3eeb5-2020.05.19"                   
    TemporarilyUnavailable:
      description: 暂时不可用
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
            - errorCode: TI-API-0503
              type: Unknown
              reason: Service unavailable                
              message: This service is temporarily unavailable. Please contact support.
            - errorCode: ERR-TICOM-FIR-API-ERP-0503
              type: Unknown
              reason: Service unavailable                
              message: This service is temporarily unavailable. Please contact support.      
            - errorCode: ERR-TICOM-FIR-API-STR-0503
              type: Unknown
              reason: Service unavailable                
              message: This service is temporarily unavailable. Please contact support.                                    
  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: {}
  schemas:
    InvoiceRetrieveResponse:
      type: object
      properties:
        orderNumber:
          type: string
          description: 供应商销售订单号 
          example: T10999999      
        financialDocumentNumber:
          type: string
          description: 供应商单据编号
          example: 5999999999
        requestPDF:
          type: string
          description: 是否包含 base64 编码的 PDF
          example: true       
        totalNumberOfDocuments:
          type: string
          description: 符合输入条件的单据总数。单个请求可以返回的最大单据数为 100。
          example: 1
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    Document:
      type: object
      properties:
        documentType:
          type: string
          description: 供应商单据类型
          example: INVOICE
        financialDocumentNumber:
          type: string
          description: 供应商单据编号
          example: 5999999999
        documentCreatedDate:
          type: string
          description: 供应商单据创建日期 (YYYY-MM-DD)
          example: 2022-08-01
        status:
          type: string
          description: 供应商单据状态
          example: CLEARED
        currencyCode:
          type: string
          description: 供应商单据币种
          example: CNY
        customerPurchaseOrderNumber:
          type: string
          description: 客户 PO 编号
          example: PGR - 04202021
        customerReferenceNumber:
          type: string
          description: 客户参考编号
          example: 0614107545
        letterOfCredit:
          type: string
          description: 客户信用证
          example: 
        shippingType:
          type: string
          description: 供应商发货类型
          example:
        grossWeight:
          type: string
          description: 供应商毛重
          example: 3.232
        netWeight:
          type: string
          description: 供应商净重
          example: 3.232
        weightUnit:
          type: string
          description: 供应商重量单位
          example: GRM
        carrier:
          type: string
          description: 供应商承运商
          example: S F EXPRESS
        taxExemptionNumber:
          type: string
          description: 客户免税编号
        documentPDF:
          type: string
          description: PDF 格式的供应商单据（base64 编码字符串）
          example: 
        documentValue:
          $ref: '#/components/schemas/DocumentValue'
        salesOrder:
          $ref: '#/components/schemas/SalesOrder'
        bankInformation:
          $ref: '#/components/schemas/BankInformation'
        VATInformation:
          $ref: '#/components/schemas/VATInformation'
        paymentTerms:
          $ref: '#/components/schemas/PaymentTerms'
        creditManager:
          $ref: '#/components/schemas/CreditManager'
        delivery:
          $ref: '#/components/schemas/Delivery'
        waybill:
          $ref: '#/components/schemas/Waybill'
        partners:
          type: array
          items:
            $ref: '#/components/schemas/Partner'
        headerPassthrough:
          type: array
          items:
            $ref: '#/components/schemas/HeaderPassthrough'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
    DocumentValue:
      type: object
      properties:
        shippingCosts:
          type: string
          description: 供应商运输成本
          example:  0.00
        handlingCosts:
          type: string
          description: 供应商处理成本
          example: 0.00
        freight:
          type: string
          description: 供应商运费
          example: 
        totalAmountSubjectToVAT:
          type: string
          description: 供应商需缴纳增值税的总金额
          example: 
        totalAmountSubjectToZeroVAT:
          type: string
          description: 供应商无增值税的总金额
          example: 
        totalVATAmount:
          type: string
          description: 供应商增值税总额
          example: 
        totalTaxAmount:
          type: string
          description: 供应商总税额
          example: 
        totalGSTAmount:
          type: string
          description: 供应商 GST 总额
          example: 
        totalAmount:
          type: string
          description: 供应商总金额
          example: 69.28
    SalesOrder:
      type: object
      properties:
        orderNumber:
          type: string
          description: TI 销售订单号
          example: T02281839
        lineItemNumber:
          type: string
          description: TI 销售订单项目编号
          example: 000010
        customerPurchaseOrderNumber:
          type: string
          description: 客户 PO 编号
          example: PO1234
        customerPurchaseOrderLineItemNumber:
          type: string
          description: 客户 PO 项目
          example: 
        purchaseOrderDate:
          type: string
          description: 客户 PO 日期
          example: 2020-01-01
        referenceDocumentNumber:
          type: string
          description: 供应商订单参考编号
          example: 
    BankInformation:
      type: object
      properties:
        bankSWIFTCode:
          type: string
          description: 客户银行 SWIFT 代码
          example: CITISWIFTCODE
        bankRoutingNumber:
          type: string
          description: 客户银行汇款线路号码
          example: 123456789
        bankAccountNumber:
          type: string
          description: 客户银行帐号
          example: 9876543 77777
    VATInformation:
      type: object
      properties:
        senderVATRegistrationNumber:
          type: string
          description: 客户发件人增值税登记号
          example: 
        soldToVATRegistrationNumber:
          type: string
          description: 客户售给方增值税登记号
          example: 
        shipToVATRegistrationNumber:
          type: string
          description: 客户收货方增值税登记号
          example: 
        billToVATRegistrationNumber:
          type: string
          description: 客户收票人增值税登记号
          example: 
        fiscalRepresentativeVATRegistrationNumber:
          type: string
          description: 供应商财务代表增值税登记号
          example: 
        GSTNumber:
          type: string
          description: 供应商 GST 编号
          example: MN00000000
        VATText:
          type: string
          description: 供应商增值税文本
          example: 
        VATCurrencyText:
          type: string
          description: 供应商增值税币种文本
          example: 
        VATTotalText:
          type: string
          description: 供应商增值税总额文本
          example: 
        GST:
          type: array
          items:
            $ref: '#/components/schemas/GST'
    GST:
      type: object
      properties:
        GSTText:
          type: string
          description: 供应商 GST 文本
          example: GST @ 0%
        GSTAmount:
          type: string
          description: 供应商 GST 金额
          example: 0.00
        GSTCurrency:
          type: string
          description: 供应商 GST 币种
          example: INR
    PaymentTerms:
      type: object
      properties:
        incoterms1:
          type: string
          description: 供应商 Incoterms 1
          example: TERMS1
        incoterms2:
          type: string
          description: 供应商 Incoterms 2
          example: TERMS1
        incotermsText:
          type: string
          description: 供应商 Incoterms 文本
          example: 
        termsOfDelivery:
          type: string
          description: 供应商交货条款
          example: SHIPPING TERMS
        termsOfPayment:
          type: string
          description: 供应商付款条款
          example: Net XX Days from Invoice Date
        paymentTermsText:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTermsText'
    PaymentTermsText:
      type: object
      properties:
        paymentTermsText:
          type: string
          description: 供应商付款条款文本
          example: Net XX Days from Invoice Date
    CreditManager:
      type: object
      properties:
        creditManagerName:
          type: string
          description: 供应商信贷经理姓名
          example: J Smith
        creditManagerTelephone:
          type: string
          description: 供应商信贷经理电话
          example: (222) 233-5555
        creditManagerFax:
          type: string
          description: 供应商信贷经理传真
          example: (222) 345-6666
        creditManagerEmail:
          type: string
          description: 供应商信贷经理电子邮件地址
          example: jsmith@testemail.com
    Delivery:
      type: object
      properties:
        deliveryNumber:
          type: string
          description: 供应商交货编号
          example: 5474899152
        deliveryLineItemNumber:
          type: string
          description: 供应商交货项目
          example: 000010
        deliveryDate:
          type: string
          description: 供应商交货日期
          example: 2022-08-01
        goodsMovementDate:
          type: string
          description: 供应商货物移动日期
          example: 2022-08-01
        grossWeight:
          type: string
          description: 供应商毛重
          example: 3.232
        netWeight:
          type: string
          description: 供应商净重
          example: 3.232
    Waybill:
      type: object
      properties:
        waybillNumber:
          type: string
          description: 供应商运单号
          example: 0429999420
        containerIdentifier:
          type: string
          description: 供应商集装箱 ID
          example: SF7000599991917
        carrierReference:
          type: string
          description: 供应商承运商参考
          example: SF1020122227011
        numberOfBoxes:
          type: string
          description: 供应商包装箱数量
          example: 1
    Partner:
      type: object
      properties:
        partnerTypeDescription:
          type: string
          description: 合作伙伴类型描述。这些值可以是 Sender、Remit To、Sold-to Party、Bill-to Party、Ship-to Party
          example: Bill-to Party
        partnerIdentifier:
          type: string
          description: 合作伙伴标识符
          example: 
        name1:
          type: string
          description: 名称 1
          example: TEST CUSTOMER
        name2:
          type: string
          description: 名称 2
          example: "ATTN: ACCOUNTS PAYABLE DEPT"
        name3:
          type: string
          description: 名称 3
          example: 
        name4:
          type: string
          description: 名称 4
          example: 
        streetAddress:
          type: string
          description: 街道地址
          example: 123 MAIN BLVD
        city:
          type: string
          description: 城市
          example: SAN FRANCISCO
        stateRegion:
          type: string
          description: 州/省/直辖市/自治区  
          example: CA         
        county:
          type: string
          description: 国家/地区代码
          example: 
        postalCode:
          type: string
          description: 邮政编码
          example:
        countryCode:
          type: string
          description: 国家/地区
          example: US
    HeaderPassthrough:
      type: object
      properties:
        headerPassthroughText:
          type: string
          description: 客户标头传递文本
          example: EEQ=Glass break detector
    Item:
      type: object
      properties:
        lineItemNumber:
          type: string
          description: 供应商物品编号
          example: 000010
        tiPartNumber:
          type: string
          description: 供应商物料
          example: SM1234 
        customerPartNumber:
          type: string
          description: 客户器件型号
          example: CPN5678
        customerProductIdentifier:
          type: string
          description: 客户物料编号
          example:
        tiPartDescription:
          type: string
          description: 供应商物料描述
          example: SM1234 material description
        quantity:
          type: string
          description: 供应商物品数量
          example: 2.000
        unitPrice:
          type: string
          description: 供应商单价
          example: 34.639
        netPrice:
          type: string
          description: 供应商物品净值
          example: 69.28
        grossWeight:
          type: string
          description: 供应商毛重
          example: 3.232
        netWeight:
          type: string
          description: 供应商净重
          example: 3.232
        commercialInvoiceNumber:
          type: string
          description: 供应商商业发票编号
          example: 5234567890
        salesOrder:
          $ref: '#/components/schemas/SalesOrder'
        delivery:
          $ref: '#/components/schemas/Delivery'
        itemVAT:
          type: array
          items:
            $ref: '#/components/schemas/ItemVAT'
        itemPassthrough:
          type: array
          items:
            $ref: '#/components/schemas/ItemPassthrough'
        additionalData:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalData'
        discountPromotionInformation:
          type: array
          items:
            $ref: '#/components/schemas/DiscountPromotionInformation'
    ItemVAT:
      type: object
      properties:
        taxIndicator:
          type: string
          description: 供应商纳税指标
          example: 01
        taxRate:
          type: string
          description: 供应商税率
          example: 6.250
        taxAmount:
          type: string
          description: 供应商税额
          example: 0.00
        taxJurisdiction:
          type: string
          description: 供应商税务管辖区
          example: USTX0000000000
        supplierTaxDescription:
          type: string
          description: 供应商税务描述
          example: Tax Description
    ItemPassthrough:
      type: object
      properties:
        itemPassthroughText:
          type: string
          description: 客户物品传递文本
          example: N1=ST 182255
    AdditionalData:
      type: object
      properties:
        additionalDataText:
          type: string
          description: 供应商附加数据文本
          example: Any additional supplier comments
    DiscountPromotionInformation:
      type: object
      properties:
        discountPromotionText:
          type: string
          description: 供应商折扣促销文本
          example: Subtotal
        discountPromotionAmount:
          type: string
          description: 供应商折扣促销金额
          example: 0.00
        discountPromotionCurrency:
          type: string
          description: 供应商折扣促销币种
          example: INR
    Error:
      type: object
      description: 标准错误消息
      properties:
        errors:
          type: array
          items:  
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      properties:
        errorCode:
          type: string
          description: 已返回错误的唯一代码。
          example: ERR-TICOM-FIR-API-0400
        type:
          type: string 
          description: 错误的分类。
          example: Validation           
        section:
          type: string
          description: 提供可找到请求违规字段的段（如果适用）。
          example: shipFromDetails          
        field:
          type: string 
          description: 验证失败的字段的名称（如果适用）。
          example: orderNumber             
        reason:
          type: string 
          description: 产生错误的原因。详细说明请求被拒绝的原因。
          example: Invalid orderNumber                                              
        message:
          type: string
          description: 具体错误的详细信息以及要采取的解决措施。
          example: orderNumber is not valid. Please provide a valid orderNumber          