第三方系统对接API文档

信安系统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

创建新的运输订单。

请求参数

{
  // 基本订单信息
  "project_id": 2001, // 项目ID，项目上线时由项目经理提供
  "contact_person": "王经理", // 联系人姓名
  "contact_phone": "13800138000", // 联系人电话
  "order_at": "2023-05-01 10:30", // 下单时间
  "email_feedback": "feedback@company.com", // 邮件反馈地址
  "customer_order_number": "PO-20230501-001", // 客户订单号
  
  // 运输配置
  "transport_temperature": 1, // 运输温度（参考配置选项）
  "order_type": 1, // 订单类型（参考配置选项）
  "cargo_type": 1, // 货物类型（参考配置选项）
  "order_level": 1, // 订单级别（参考配置选项）
  "transport_duration": 1, // 运输时效（参考配置选项）
  "transport_mode": 1, // 运输方式（参考配置选项）
  "temperature_humidity_recorder": 1, // 温湿度记录仪（参考配置选项）
  
  // 保险相关
  "is_insure": 1, // 是否保险（0=否，1=是）
  "declared_value": 5000.00, // 声明价值（当is_insure=1时必填）
  
  // 发件信息
  "sender_city_id": 1, // 发件城市ID

  "sender_customer_name": "北京医药公司", // 发件客户名称
  "pickup_date": "2023-05-10", // 预取日期
  "pickup_start_at": "2023-05-10 09:00", // 预取开始时间
  "pickup_end_at": "2023-05-10 12:00", // 预取结束时间
  "sender_name": "张三", // 发件人姓名
  "sender_phone": "13800138000", // 发件人电话
  "sender_address": "北京市朝阳区XX路XX号", // 发件人地址
  
  // 收件信息
  "receiver_city_id": 2, // 收件城市ID

  "receiver_customer_name": "上海医院", // 收件客户名称
  "delivery_date": "2023-05-12", // 预派日期
  "delivery_start_at": "2023-05-12 14:00", // 预派开始时间
  "delivery_end_at": "2023-05-12 18:00", // 预派结束时间
  "receiver_name": "李四", // 收件人姓名
  "receiver_phone": "13900139000", // 收件人电话
  "receiver_address": "上海市浦东新区XX路XX号", // 收件人地址
  
  // 其他选项
  "is_receipt_return": 0, // 需要回单（0=否，1=是，默认0）
  "remark": "易碎品，小心轻放" // 备注信息
}

字段说明

基本订单信息
字段名称 字段类型 是否必填 字段解释
project_id Integer 是 项目ID，项目上线时由项目经理提供
contact_person String 否 联系人姓名
contact_phone String 否 联系人电话
order_at DateTime 是 下单时间（格式：YYYY-MM-DD HH:mm）
email_feedback String 否 邮件反馈地址
customer_order_number String 否 客户订单号
运输配置
字段名称 字段类型 是否必填 字段解释
transport_temperature Integer 是 运输温度（参考配置选项）
order_type Integer 是 订单类型（参考配置选项）
cargo_type Integer 是 货物类型（参考配置选项）
order_level Integer 是 订单级别（参考配置选项）
transport_duration Integer 是 运输时效（参考配置选项）
transport_mode Integer 是 运输方式（参考配置选项）
temperature_humidity_recorder Integer 是 温湿度记录仪（参考配置选项）
保险相关
字段名称 字段类型 是否必填 字段解释
is_insure Integer 是 是否保险（0=否，1=是）
declared_value Decimal 条件必填 声明价值（当is_insure=1时必填）
发件信息
字段名称 字段类型 是否必填 字段解释
sender_city_id Integer 是 发件城市ID
sender_customer_name String 否 发件客户名称
pickup_date Date 是 预取日期
pickup_start_at DateTime 是 预取开始时间
pickup_end_at DateTime 是 预取结束时间
sender_name String 是 发件人姓名
sender_phone String 是 发件人电话
sender_address String 是 发件人地址
收件信息
字段名称 字段类型 是否必填 字段解释
receiver_city_id Integer 是 收件城市ID
receiver_customer_name String 否 收件客户名称
delivery_date Date 是 预派日期
delivery_start_at DateTime 是 预派开始时间
delivery_end_at DateTime 是 预派结束时间
receiver_name String 是 收件人姓名
receiver_phone String 是 收件人电话
receiver_address String 是 收件人地址
其他选项
字段名称 字段类型 是否必填 字段解释
is_receipt_return Integer 否 需要回单（0=否，1=是，默认0）
remark Text 否 备注信息

必填字段

  • project_id - 项目ID
  • order_at - 下单时间
  • transport_temperature - 运输温度
  • order_type - 订单类型
  • cargo_type - 货物类型
  • order_level - 订单级别
  • transport_duration - 运输时效
  • transport_mode - 运输方式
  • temperature_humidity_recorder - 温湿度记录仪
  • is_insure - 是否保险
  • sender_city_id - 发件城市ID
  • pickup_date - 预取日期
  • pickup_start_at - 预取开始时间
  • pickup_end_at - 预取结束时间
  • sender_name - 发件人姓名
  • sender_phone - 发件人电话
  • sender_address - 发件人地址
  • receiver_city_id - 收件城市ID
  • delivery_date - 预派日期
  • delivery_start_at - 预派开始时间
  • delivery_end_at - 预派结束时间
  • receiver_name - 收件人姓名
  • receiver_phone - 收件人电话
  • receiver_address - 收件人地址

条件必填字段

  • declared_value - 声明价值（当is_insure=1时必填）

重要说明

  1. 防重复提交：API有2秒的防重复提交机制
  2. 配置选项：所有带"参考配置选项"的字段，其可选值可通过 /api/order/config 接口获取
  3. 条件验证：declared_value 字段仅在 is_insure=1 时为必填
  4. 时间格式：datetime字段格式为 YYYY-MM-DD HH:mm，date字段格式为 YYYY-MM-DD

响应示例

{
    "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,
        "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_customer_name": 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_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在系统中是唯一的，可以用于查询订单相关信息