第三方系统对接API文档

1. 接口概述

本文档提供信安与第三方系统对接的API接口规范，包括认证方式、接口列表、请求参数及响应格式等内容。

2. 认证方式

基础请求信息

请求Host：https://oms.xinans.com

Content-Type：application/json

认证参数

所有API请求必须在请求头中包含以下认证参数：

参数名	类型	必填	说明
X-App-Id	String	是	应用ID，由系统分配
X-App-Secret	String	是	应用密钥，由系统分配

3.1 获取订单配置信息

GET/api/order/config

获取创建订单所需的配置信息，包括城市列表、运输温度、订单类型等。

请求参数

无

响应示例

{
    "city": [
        {
            "id": 152900,
            "name": "阿拉善盟"
        },
        {
            "id": 820000,
            "name": "澳门"
        }
    ],
    "transport_temperature": [
        {
            "id": 11,
            "name": "常温"
        },
        {
            "id": 21,
            "name": "恒温18~25℃"
        }
    ],
    "transport_duration": [
        {
            "id": "4h",
            "name": "4h"
        }
    ],
    "is_insure": [
        {
            "id": 0,
            "name": "不投保"
        },
        {
            "id": 1,
            "name": "投保"
        }
    ],
    "order_type": [
        {
            "id": 1,
            "name": "运输订单"
        }
    ],
    "cargo_type": [
        {
            "id": 3,
            "name": "样本"
        }
    ],
    "order_level": [
        {
            "id": 0,
            "name": "普通"
        }
    ],
    "transport_mode": [
        {
            "id": 0,
            "name": "普通"
        }
    ],
    "temperature_humidity_recorder": [
        {
            "id": 1,
            "name": "无温度计"
        }
    ],
    "is_receipt_return": [
        {
            "id": 1,
            "name": "是"
        },
        {
            "id": 0,
            "name": "否"
        }
    ]
}

3.2 创建订单

POST/api/order/create

创建新的运输订单。

请求参数

{
  "customer_order_number": "PO-20230501-001", // 客户订单号
  "transport_temperature": 1, // 运输温度
  "transport_duration": 1, // 运输时长要求
  "is_insure": 0, // 是否投保(0:否,1:是)
  "declared_value": 0, // 声明价值(投保时必填)
  "is_receipt_return": 0, // 是否需要回单(0:否,1:是)
  "order_type": 1, // 订单类型
  "cargo_type": 1, // 货物类型
  "order_level": 1, // 订单等级
  "transport_mode": 1, // 运输方式
  "temperature_humidity_recorder": 1, // 温湿度记录仪类型
  "sender_city_id": 1, // 发货城市ID
  "pickup_date": "2023-05-10", // 预取日期
  "pickup_start_at": "09:00", // 预取开始时间
  "pickup_end_at": "12:00", // 预取结束时间
  "sender_name": "张三", // 发货人姓名
  "sender_phone": "13800138000", // 发货人电话
  "sender_address": "北京市朝阳区XX路XX号", // 发货地址
  "receiver_city_id": 2, // 收货城市ID
  "delivery_date": "2023-05-12", // 预派日期
  "delivery_start_at": "14:00", // 预派开始时间
  "delivery_end_at": "18:00", // 预派结束时间
  "receiver_name": "李四", // 收货人姓名
  "receiver_phone": "13900139000", // 收货人电话
  "receiver_address": "上海市浦东新区XX路XX号", // 收货地址
  "remark": "易碎品，小心轻放", // 备注
}

必填字段

transport_temperature
transport_duration
is_insure
order_type
cargo_type
order_level
transport_mode
temperature_humidity_recorder
sender_city_id
pickup_date
pickup_start_at
pickup_end_at
sender_name
sender_phone
sender_address
receiver_city_id
delivery_date
delivery_start_at
delivery_end_at
receiver_name
receiver_phone
receiver_address

响应示例

{
    "msg": "success",
    "data": {
        "order_id": 10001
    }
}

3.3 获取订单详情

GET/api/order/detail?id={order_id}

根据订单ID获取订单详细信息。

请求参数

参数名	类型	必填	说明
id	Integer	是	订单ID（URL查询参数）

响应示例

{
    "msg": "success",
    "data": {
        "id": 10041,
        "customer_id": 10000026,
        "project_id": 28,
        "contact_person": null,
        "contact_phone": null,
        "order_at": "2024-05-20 23:44:00",
        "email_feedback": null,
        "waybill_number": null,
        "transport_temperature": "常温",
        "order_type": "运输订单",
        "cargo_type": "细胞",
        "customer_order_number": null,
        "order_level": "普通",
        "transport_duration": "48h",
        "transport_mode": "普通",
        "is_insure": "不投保",
        "declared_value": 0,
        "temperature_humidity_recorder": "无温度计",
        "temperature_number": 0,
        "humidity_range": "",
        "sender_city_id": 654300,
        "sender_child_city_id": 0,
        "sender_customer_id": null,
        "sender_customer_name": null,
        "sender_center_id": null,
        "pickup_date": "2024-05-20",
        "pickup_start_at": "23:45:12",
        "pickup_end_at": "23:50:05",
        "sender_name": "sss",
        "sender_phone": "sss",
        "sender_address": "sss",
        "receiver_city_id": 542500,
        "receiver_child_city_id": 0,
        "receiver_customer_id": null,
        "receiver_customer_name": null,
        "delivery_date": null,
        "delivery_start_at": null,
        "delivery_end_at": null,
        "receiver_name": "ss",
        "receiver_phone": "ss",
        "receiver_address": "sss",
        "remark": null,
        "status": "新增",
        "settlement_status": 0,
        "order_data": 0,
        "temperature_data": 0,
        "picked_at": null,
        "receipt_return": 0,
        "is_receipt_return": 0,
        "created_at": "2024-05-20 23:45:32",
        "updated_at": "2024-05-20 23:45:32",
        "deleted_at": null,
        "project": {
            "id": 28,
            "name": "刘文达-新项目",
            "project_number": "CN23012-PN01"
        },
        "fcity": {
            "id": 654300,
            "province_id": 31,
            "name": "阿勒泰",
            "code": "836500",
            "paragraph": "0906",
            "version": 2
        },
        "scity": {
            "id": 542500,
            "province_id": 26,
            "name": "阿里地区",
            "code": "859100",
            "paragraph": "0897",
            "version": 2
        }
    }
}

3.4 获取订单附件列表

GET/api/order/attachments?id={order_id}

获取订单相关的附件文件列表。

请求参数

参数名	类型	必填	说明
id	Integer	是	订单ID（URL查询参数）

响应示例

{
    "msg": "获取成功",
    "data": {
        "order_attachments": [
            {
                "file_name": "订单附件.pdf",
                "file_size": 1024000,
                "file_path": "uploads/202405/order/123456.pdf",
                "url": "http://example.com/storage/uploads/202405/order/123456.pdf"
            }
        ],
        "temperature_attachments": [
            {
                "file_name": "温度记录.jpg",
                "file_size": 2048000,
                "file_path": "uploads/202405/temperature/789012.jpg",
                "url": "http://example.com/storage/uploads/202405/temperature/789012.jpg"
            }
        ],
        "flow_attachments": [
            {
                "file_name": "取件凭证.png",
                "file_size": 1536000,
                "file_path": "uploads/202405/flow/345678.png",
                "url": "http://example.com/storage/uploads/202405/flow/345678.png"
            }
        ]
    }
}

3.5 获取订单物流信息

GET/api/order/logistics?id={order_id}

获取订单的物流跟踪信息。

请求参数

参数名	类型	必填	说明
id	Integer	是	订单ID（URL查询参数）

响应示例

{
    "msg": "success",
    "data": {
        "waybill_number": "SF1234567890",
        "logistics_history": [
            {
                "date": "2024-05-20 10:30:00",
                "time": 1716181800,
                "operation_type": "取件",
                "operation_city": "北京市"
            },
            {
                "date": "2024-05-20 14:20:00",
                "time": 1716195600,
                "operation_type": "派件",
                "operation_city": "北京市"
            }
        ]
    }
}

4. 通用响应格式

所有API接口都采用统一的响应格式：

成功响应示例

{
    "msg": "success",
    "data": {
        // 具体数据内容
    }
}

失败响应示例

{
    "msg": "参数错误"
}

5. 错误码说明

常见错误码

错误信息	说明
success	请求成功
参数错误	请求参数格式错误或缺少必要参数
认证失败	API密钥无效或已过期
权限不足	当前用户无权限访问该资源
订单不存在	指定的订单ID不存在
服务器错误	服务器内部错误，请稍后重试

6. 注意事项

所有API请求都需要在请求头中包含认证信息
请求参数中的时间戳为Unix时间戳（秒）
所有接口都支持HTTPS协议，建议在生产环境中使用
API有频率限制，请合理控制请求频率
订单ID在系统中是唯一的，可以用于查询订单相关信息