# 上传物流信息

> 为支付交易上传承运商编码和物流追踪单号。

```yaml
openapi: 3.1.0
info:
  title: 上传物流信息
  version: 1.0.0
  description: 为支付交易上传承运商编码和物流追踪单号。
paths:
  /v1/txn/uploadLogisticsInfo:
    post:
      summary: 上传物流信息
      description: 为支付交易上传承运商编码和物流追踪单号。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                transactionId:
                  type: string
                  description: 本次上传物流信息对应的 Onerway 交易号，JSON 以 `String` 传输。
                  x-onerway-constraints:
                    - kind: rule
                      text: 仅可为已成功完成的交易上传物流信息。
                    - kind: rule
                      text: 再次提交相同的 `transactionId` 时，系统会用本次提交的物流信息自动覆盖已有信息。
                    - kind: unsupported
                      text: 用于 stc pay 结算时，本物流结算前置条件不支持虚拟商品交易或分期交易。
                carrierNo:
                  type: string
                  description: 物流公司编码，用于标识承运商并追踪包裹物流信息。
                  x-onerway-constraints:
                    - kind: values
                      text: 请从 [Onerway 物流公司编码列表](/downloads/payments/logistics/carrier-codes.csv)
                        选择取值；该下载列表覆盖全球 1000+ 家物流公司。
                trackingNo:
                  type: string
                  description: 物流追踪单号，由物流公司提供，用于查询包裹配送进度与签收状态。
                  x-onerway-constraints:
                    - kind: rule
                      text: 用于 stc pay 结算时，仅在包裹已送达客户并签收后上传物流信息。
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
              required:
                - merchantNo
                - transactionId
                - carrierNo
                - trackingNo
                - sign
            examples:
              upload-logistics-info:
                summary: 上传物流信息
                value:
                  carrierNo: SF
                  merchantNo: replace_with_merchant_no
                  sign: "{{SIGN}}"
                  trackingNo: SF1234567890
                  transactionId: example_transaction_id
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      respCode:
                        type: string
                        description: 响应码；`20000`
                          表示上传请求处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                      respMsg:
                        type: string
                        description: 响应码对应的可读消息。
                      data:
                        type:
                          - string
                          - "null"
                        description: 物流上传成功对应的 Onerway 交易订单号。
                        x-onerway-constraints:
                          - kind: rule
                            text: "`data` 是交易订单号字符串本身，不是嵌套对象。"
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returns the `transactionId` from the request when the upload succeeds.
                              Returns `null` for the `50018`, `50204`, and
                              `50000` error responses.
                            zh: 上传成功时返回请求中的 `transactionId`；错误响应 `50018`、`50204` 和 `50000` 中返回 `null`。
                  - type: object
                    properties:
                      respCode:
                        type: string
                      respMsg:
                        type: string
                      data:
                        type: "null"
                    required:
                      - respCode
                      - respMsg
                      - data
                  - type: object
                    properties:
                      respCode:
                        type: string
                      respMsg:
                        type: string
                      data:
                        type: "null"
                    required:
                      - respCode
                      - respMsg
                      - data
                  - type: object
                    properties:
                      respCode:
                        type: string
                      respMsg:
                        type: string
                      data:
                        type: "null"
                    required:
                      - respCode
                      - respMsg
                      - data
              examples:
                "50000":
                  summary: 保存物流信息时发生系统错误。
                  description: 系统错误
                  value:
                    respCode: "50000"
                    respMsg: System error
                    data: null
                "50018":
                  summary: 交易不存在，或不属于 `merchantNo` 指定的商户。
                  description: 交易不存在
                  value:
                    respCode: "50018"
                    respMsg: Non-existent order!
                    data: null
                "50204":
                  summary: 交易尚未成功完成，包括处理中或已失败的交易。
                  description: 交易状态不符合要求
                  value:
                    respCode: "50204"
                    respMsg: Wrong order status!
                    data: null
```