• 开发须知

     

    目前优志成CMS所有的开放能力皆为内测阶段,暂不开放所有接口,请注意:

    调用优志成服务端接口时,需使用HTTPS协议、JSON或FORM数据格式、UTF-8编码。

    在调用API前,确保您已了解调用频率限制为30QPS/s。

    query指该参数需在请求URL传参

    body指该参数需在请求JSON传参

     

    基础概念 

    ISV 身份

    授权对象ISV即服务商、应用开发者。

    APP 身份

    授权对象APP即开放应用/配送应用,由服务商进行管理、开发的应用。

    ApiKey/ApiSecret

    ApiKey是服务商ISV调用API的唯一身份标识,ApiSecret是对应的API密钥。 AppId/AppSecret

    AppId是开放应用/配送应用APP的唯一身份标识,AppSecret是对应的应用的密钥

     

    HTTP Headers

     

    HTTP Header 描述
    Authorization 用于验证请求合法性的认证信息。请严格按照签名格式进行填充,否则会返回401 HTTP状态码。
    Content-Type 请求或响应内容的 MIME 类型。例如Content-Type: application/json;charset=UTF-8或application/x-www-form-urlencoded。
    User-Agent 每次请求中此HTTP Header会标识自己,若没有此信息将会拒绝请求。
    X-APPID ApiKey或者AppId。
    X-Source ISV或者APP。
    X-Expiration 请求时间,请使用Unix时间戳。
    X-Host 服务器域名。例如X-Host: https://api.boolc.cn。

     

    响应格式

    通过API请求,响应头部信息包括:

    2xx、3xx、4xx、5xx的HTTP状态码

    Content-Type: application/json;charset=UTF-8

     

    数据格式

    HTTP状态码为2xx,接口状态码为2xxxx,API执行后将返回一个JSON格式的信息对象。具体格式如下:

    {
    	"code": <Code int>,
    	"data": <Data interface{}>,
        "msg": "<Msg string>"
    }
    Key 描述
    code 接口状态码,该状态码不同于HTTP状态码,是接口定义的状态码。
    data 接口返回的数据,详见对应接口的响应数据。
    msg 正确/错误返回信息提示。

     

    接口状态码

    状态码 描述
    20000 接口请求成功。
    40001 参数方面的异常状态,如参数格式错误、参数长度错误等。
    40003 鉴权失败,若在网关鉴权错误HTTP状态码为2xx,若在服务内部鉴权错误HTTP状态码为401。
    40005 系统维护、更新等状态产生的问题。
    40008 未经授权的系统,和40003区别在于系统鉴权问题,将会记录黑名单。
    50000 系统错误,请将请求头、参数、签名等信息截图交由技术协调处理。
    50001 未知错误,请将请求头、参数、签名等信息截图交由技术协调处理。
    50008 Token非法、失效等情况返回的状态码。

     

    签名

    API通过验证签名来保证请求的真实性和数据的完整性。

     

    请求签名

     

    请使用ApiKey/ApiSecret或AppId/AppSecret对API HOST、Body等关键数据的组合进行HmacSHA256签名。

    请求签名通过HTTP Header Authorization传递,具体说明请见下方说明。没有携带签名或者签名验证不通过的请求,都不会被执行,并返回401 Unauthorized。

     

     

  • 配送应用

    接口 描述
    PrepareAddOrder 预下单,将订单信息发送,计算订单配送费,再决定是否下单配送
    AddOrder 新增配送订单进行配送
    OrderDetail 获取订单详细信息,包含订单状态、起送地址等信息。
    OrderLog 获取订单操作日志信息
    OrderDelivererLoc 获取配送员地理位置,位置信息15-30秒更新一次
    PrepareCancelOrder 预取消订单,商家准备取消订单之前的操作
    CancelOrder 取消订单,商家主动取消订单
    OrderReminder 催单,每十分钟只能催促一次
    OrderNotify 订单回调,将订单状态和相关订单信息回传给系统

     

     

     

  • 预下单

    描述

    将订单信息发送,计算订单配送费,再决定是否下单配送。

     

    接口说明

     

    授权对象 APP

    请求地址 POST /open/order/prepareAddOrder

     

     

    请求参数

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    商品列表 goods []object body
    商户信息 merchant object body
    收件人 receive object body
    平台商户ID merchant_id uint32 body在系统后台获取。

    示例值:1

    对接订单号 order_number string[1,64] body即对接平台的订单号,用于唯一标识订单。

    示例值:2022082812341234

    预计取餐时间 scheduled_time int64 body时间戳

    示例值:1660134369

    是否预约单 is_reserve int8 body0:即时单,1:预约单。

    示例值:1

    重量 weight uint32 body单位:克

    示例值:600

    数量 quantity uint32 body商品数量。

    示例值:1

     

     

    商品列表 goods

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    商品名称 title string[1, 64]

    示例值:包子

    数量 num uint32

    示例值:1

    重量 weight uint32 单位:克

    示例值:100

    价格 price double

    示例值:5.1

     

     

    商户信息 merchant

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    店铺名称 title string[1,64]

    示例值:优志成商店

    联系方式 mobile int64

    示例值:18866668888

    店铺地址 address string[1,256]

    示例值:苏州产业园区

    经度 lng double 精确到后6位

    示例值:109.110275

    纬度 lat double 精确到后6位

    示例值:21.443884

     

     

    收件人信息 receive

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    收件人 username string[1,64]

    示例值:YZC

    联系方式 mobile int64

    示例值:18888888888

    收件地址 address string[1,256]

    示例值:苏州科技大学

    经度 lng double 精确到后6位

    示例值:109.110275

    纬度 lat double 精确到后6位

    示例值:21.443884

     

     

    请求示例

     

    {
      "duration": 60,
      "goods": [
        {
          "title": "包子",
          "num": 1,
          "price": 5.1,
          "weight": 100
        }
      ],
      "order_detail": {
        "total_price": 6,
        "delivery_money": 1
      },
      "receive": {
        "username": "BOOL",
        "mobile": "18888888888",
        "lng": 109.110275,
        "lat": 21.443884,
        "address": "贵州省花溪区贵州大学东校区10栋"
      },
      "merchant": {
        "title": "BOOL商店",
        "mobile": "18866668888",
        "lng": 109.110275,
        "lat": 21.443884,
        "address": "贵州省贵安新区数字经济产业园"
      },
      "expect_time": 1660134369,
      "order_number": "2022082812341234",
      "scheduled_time": 1660134999,
      "is_reserve": 2,
      "weight": 100,
      "quantity": 1,
      "merchant_id": 1
    }

     

  • 描述

    使用此接口新增配送订单进行配送。

    接口说明

     

    授权对象 APP

    请求地址 POST /open/order/order

     

    请求参数

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    商品列表 goods []object body
    商户信息 merchant object body
    收件人 receive object body
    平台商户ID merchant_id uint32 body在系统后台获取。

    示例值:1

    对接订单号 order_number string[1,64] body即对接平台的订单号,用于唯一标识订单。

    示例值:2022082812341234

    取货码 code string[1,64] body即对接平台的取货码不传不显示给配送员。

    示例值:2022082812341234

    期望送达时间 scheduled_time int64 body时间戳

    示例值:1660134369

    期望取餐时间 expect_time int64 body时间戳

    示例值:1660134369

    是否预约单 is_reserve int8 body0:即时单,1:预约单。

    示例值:1

    重量 weight uint32 body单位:克

    示例值:600

    数量 quantity uint32 body商品数量。

    示例值:1

    本地短订单号 day_num uint32 body商户订单号,一般为当日订单号。会显示为#1。

    示例值:1

    来源描述 source_desc string[1,64] body平台名称,可自定义。

    示例值:美团

    取货码 code uint32 body骑手可通过取货码查询订单。

    示例值:100001

    备注 remark string[1,256] body订单备注

    示例值:十万火急

    回调链接 callback_url string[1,256] body

    示例值:https://api.suzhouyzc.cn/notify/open/delivery

    回调参数 callback_scene string[1,256] body回传参数,传什么内容皆会在回调时返回同样的数据。
    接口 描述
    PrepareAddOrder 预下单,将订单信息发送,计算订单配送费,再决定是否下单配送
    AddOrder 新增配送订单进行配送
    OrderDetail 获取订单详细信息,包含订单状态、起送地址等信息。
    OrderLog 获取订单操作日志信息
    OrderDelivererLoc 获取配送员地理位置,位置信息15-30秒更新一次
    PrepareCancelOrder 预取消订单,商家准备取消订单之前的操作
    CancelOrder 取消订单,商家主动取消订单
    OrderReminder 催单,每十分钟只能催促一次
    OrderNotify 订单回调,将订单状态和相关订单信息回传给系统

     

     

     

    商品列表 goods

     

     

    参数名称

    变量名称

    参数类型[长度限制]

    是否必填

    描述

    商品名称

    title

    string[1, 64]

    示例值:包子

    数量

    num

    uint32

    示例值:1

    重量

    weight

    uint32

    单位:克

    示例值:100

    价格

    price

    double

    示例值:5.1

     

     

    商户信息 merchant

     

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    店铺名称 title string[1,64]

    示例值:优志成商店

    联系方式 mobile int64

    示例值:18866668888

    店铺地址 address string[1,256]

    示例值:苏州数字经济产业园

    经度 lng double 精确到后6位

    示例值:109.110275

    纬度 lat double 精确到后6位

    示例值:21.443884

     

     

  •  

    描述

     

    使用此接口获取订单详细,包含订单状态、起送地址等信息。

     

    接口说明

     

    授权对象 APP

    请求地址 GET /open/order/order

     

     

    请求参数

     

    参数名称

    变量名称

    参数类型[长度限制]

    是否必填

    描述

    对接订单号

    order_number

    string[1, 64]

    二选一

    query

    平台订单号

    transaction_id

    string[1, 64]

    二选一

    query

     

     

    请求示例

     

    {
      "order_number": "2022082812341234"
    }

     

     

    响应结果

     

    参数名称 变量名称 参数类型[长度限制] 是否必填 描述
    商品列表 goods []object  
    商户信息 merchant object  
    收件人 receive object  
    平台商户ID merchant_id uint32 在系统后台获取。

    示例值:1

    对接订单号 order_number string[1,64] 即对接平台的订单号,用于唯一标识订单。

    示例值:2022082812341234

    计划配送时长 duration uint32 不传则默认,单位:分钟

    示例值:60

    预计送达时间 expect_time int64 时间戳

    示例值:1660134369

    预计取餐时间 scheduled_time int64 时间戳

    示例值:1660134369

    是否预约单 is_reserve int8 0:即时单,1:预约单。

    示例值:1

    重量 weight uint32 单位:克

    示例值:600

    数量 quantity uint32 商品数量。

    示例值:1

    本地短订单号 day_num uint32 商户订单号,一般为当日订单号。会显示为#1。

    示例值:1

    来源描述 source_desc string[1,64] 平台名称,可自定义。

    示例值:美团

    取货码 code uint32 骑手可通过取货码查询订单。

    示例值:100001

    备注 remark string[1,256] 订单备注

    示例值:十万火急

    平台订单号 transaction_id string[1,64]

    示例值:2022082818035691363043

    配送状态 delivery_status int8 1:待接单,2:已接单,3:已到店,4:已取件,5:已送达,6:已完成,8:配送取消,11:配送异常

    示例值:1