创建代理专线订单流程

Owned by Seven Zhang
Last updated: 2021-01-21 by tuhao
24 min read

建立连接

在创建订单前， 我们先要了解如何建立连接。

鸟系统是使用Restful API与第三方系统交互的。为了识别用户身份，需要在每个请求中包含身份标识，这个动作我们称为建立连接， 可参考链接 ：建立连接

目前创建专线代理订单有两种方式, 一种是单个添加, 一种是批量添加

建议使用批量添加

一.批量添加

注意, 使用批量添加, 订单状态默认是到"已完成", 自己出单就不用管了, 如果包裹发到鸟仓再出单, 则需要给每个consignment添加"status":"PENDING"的参数

获取预置信息

创建订单的时候, 需要邮递服务和包裹尺寸, 可以预存到你们系统里, 不经常改变, 不需要每次都请求.

获取邮递服务

地址: GET http://test.birdsystem.com/client/delivery-service?consignment_type=AGENT_DIRECT

返回

{
    "total": 11,
    "data": [ 
        {
            "id": 5371,
            "company_id": 36,
            "restrict_max_length_contact": "35",
            "restrict_max_length_address_line1": "35",
            "restrict_max_length_address_line2": "35",
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": "^.{7,32}$",
            "name": "D 中德快线(M)",
            "locale_name": "DL TRACK DE FQB",
            "is_signature": "0",
            "is_tracking": "1",
            "is_express": "0",
            "is_international": "1",
            "is_customs_required": "0",
            "is_check_post_code": "1",
            "is_check_telephone": "1",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "VIWO2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5304,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": "^.{0,25}$",
            "name": "D 中澳平邮(M)",
            "locale_name": "中澳平邮电池(M)",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "1",
            "is_customs_required": "0",
            "is_check_post_code": "1",
            "is_check_telephone": "1",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "SAICHENG_LOGISTICS",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5432,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": "^.{0,25}$",
            "name": "D 中澳跟踪(M)",
            "locale_name": "中澳跟踪(M)",
            "is_signature": "0",
            "is_tracking": "1",
            "is_express": "0",
            "is_international": "1",
            "is_customs_required": "0",
            "is_check_post_code": "1",
            "is_check_telephone": "1",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "SAICHENG_LOGISTICS",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5198,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英平邮（B2P）",
            "locale_name": "D AGENT UNTRACK UK 24",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5407,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英平邮（B2P） 带电",
            "locale_name": "D AGENT UNTRACK UK24 ##",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5399,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英标准简易跟踪",
            "locale_name": "D STANDARD SIMPLE TRACK UK 24 ",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5409,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英标准简易跟踪 带电",
            "locale_name": "D STANDARD SIMPLE TRACK UK 24 ##",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5202,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英跟踪（B2P）",
            "locale_name": "D AGENT TRACK UK 48",
            "is_signature": "0",
            "is_tracking": "1",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5408,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "D 中英跟踪（B2P） 带电",
            "locale_name": "D AGENT TRACK UK 48 ##",
            "is_signature": "0",
            "is_tracking": "1",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5379,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": "([A-PR-UWYZa-pr-uwyz0-9][A-HK-Ya-hk-y0-9][A-Za-z0-9]?[A-Za-z0-9]? {0,2}-?[0-9][ABD-HIJLN-UW-Zabd-hijln-uw-z]{2}|GIR 0AA)",
            "restrict_regex_telephone": null,
            "name": "D 平邮标准RM Packet",
            "locale_name": "AGENT UNTRACK RM Packet",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RMONLINE",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 5412,
            "company_id": 36,
            "restrict_max_length_contact": null,
            "restrict_max_length_address_line1": null,
            "restrict_max_length_address_line2": null,
            "restrict_max_length_address_line3": null,
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": "([A-PR-UWYZa-pr-uwyz0-9][A-HK-Ya-hk-y0-9][A-Za-z0-9]?[A-Za-z0-9]? {0,2}-?[0-9][ABD-HIJLN-UW-Zabd-hijln-uw-z]{2}|GIR 0AA)",
            "restrict_regex_telephone": null,
            "name": "D 平邮标准RM Packet 带电",
            "locale_name": "AGENT UNTRACK RM Packet ##",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "1",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "is_hide_delivery_reference_to_consignment": "0",
            "special_type": "RMONLINE",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
    ],
    "success": true,
    "moduleName": "client"
}

创建订单

地址: POST http://test.birdsystem.com/client/consignment/Post-Pending-Consignment-With-Products-Json?type=agent_direct

参数

[
  {
    "delivery_service_id": "5198",
       "type":"AGENT_DIRECT",
    "business_name": "",
    "contact": "Rochelle Kerr",
    "address_line1": "23 Portelet Court",
    "city": "London",
    "county": "London",
    "post_code": "N1 5TL",
    "country_iso": "GB",
    "telephone": "07983-467763-467763",
    "custom_identity_reference":"24SF242321",
    "line": "1",
    "products": [
      {
        "product_name": "3apple29",
        "product_name_cn":"3苹果29",
        "brand":"asd品牌",
        "client_ref":"a4624",
        "price_customs_export": "3",
        "weight": "300",
        "quantity": "1",
        "product_customs_property":["其它"],
        "attachment-url":"http://www.qqma.com/imgpic2/cpimagenew/2018/4/5/6e1de60ce43d4bf4b9671d7661024e7a.jpg"
      },
       {
        "product_name": "4apple29",
        "product_name_cn":"4苹果29",
        "brand":"asd品牌",
        "client_ref":"a5456",
        "price_customs_export": "3",
        "weight": "300",
        "quantity": "1",
        "product_customs_property":["其它"],
        "attachment-url":"http://www.qqma.com/imgpic2/cpimagenew/2018/4/5/6e1de60ce43d4bf4b9671d7661024e7a.jpg"
      }
    ]
  }
]

line: 创建失败的时候, 会告知是哪一个line出错.

其他每个字段的含义, 请参考创建专线代理订单流程-创建订单.2


返回

{
    "success": true,
    "data": {
        "1904090360000029": "0B0438737000000004773",
        "1904090360000030": "GG000008145GB"
    },
    "moduleName": "client"
}

data是创建成功的订单号和跟踪号的键值对 json对象


二.单个添加

创建订单

获取预置信息

创建订单的时候, 需要邮递服务和包裹尺寸, 可以预存到你们系统里, 不经常改变, 不需要每次都请求.

获取邮递服务

地址: GET http://test.birdsystem.com/client/delivery-service?type=AGENT_DIRECT

返回

{
            "id": 2667,
            "company_id": 36,
            "restrict_max_length_contact": "35",
            "restrict_max_length_address_line1": "35",
            "restrict_max_length_address_line2": "35",
            "restrict_max_length_address_line3": "35",
            "restrict_max_length_post_code": null,
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "代理平邮UK24",
            "locale_name": "AGENT UNTRACK UK 24",
            "is_signature": "0",
            "is_tracking": "0",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "0",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        },
        {
            "id": 2668,
            "company_id": 36,
            "restrict_max_length_contact": "35",
            "restrict_max_length_address_line1": "35",
            "restrict_max_length_address_line2": "35",
            "restrict_max_length_address_line3": "35",
            "restrict_max_length_post_code": "0",
            "restrict_regex_post_code": null,
            "restrict_regex_telephone": null,
            "name": "代理跟踪UK48",
            "locale_name": "AGENT TRACK UK 48",
            "is_signature": "0",
            "is_tracking": "1",
            "is_express": "0",
            "is_international": "0",
            "is_customs_required": "0",
            "is_check_post_code": "1",
            "is_check_telephone": "0",
            "is_allow_urgent_consignment": "1",
            "special_type": "RM2",
            "consignment_type": "AGENT_DIRECT",
            "consignment_notice_enable": "0",
            "consignment_notice": "",
            "status": "ACTIVE"
        }


获取包裹尺寸

地址:  GET http://test.birdsystem.com/client/Delivery-Package-Size/Get-By-Delivery-Service-Id/

参数

//获取哪个邮递服务的包裹尺寸
delivery_service_id=2667


返回

{
    "total": 1,
    "data": [
        {
            "id": 741,
            "company_id": 36,
            "consignment_delivery_agent_id": 143,
            "name": "代理专线服务专用尺寸",
            "code": "",
            "external_code": null,
            "limitation_formula": "{length}>0",
            "volume_factor": "1.10",
            "length": "0.00",
            "width": "0.00",
            "depth": "0.00",
            "list_order": "0",
            "status": "ACTIVE",
            "primary_keys": [
                "id"
            ]
        }
    ],
    "success": true,
    "refresh": false,
    "moduleName": "client"
}


创建订单

地址: POST http://test.birdsystem.com/client/Consignment/

参数

//服务id
delivery_service_id=2667
//包裹尺寸id
delivery_package_size_id=741
//收件人
contact=Paul Mcquaid
//公司名
business_name=
//收件人电话
telephone=07887 567217
//收件地址
address_line1=Penmarric Parish Rd
address_line2=
address_line3=
//收件城市
city=Minster On Sea
//收件省/郡
county=Kent
//收件人邮编
post_code=ME12 3NG
//收件人国家
country_iso=GB
//发件人国家
sender_country_iso=GB
//订单类型
type=AGENT_DIRECT


返回

{
    "data": {
        "commodity_code": null,
        "total_price_customs_export": null,
        "name_customs": null,
        "total_quantity": null,
        "weight": null,
        "price": null,
        "price_customs_export": null,
        "period": null,
        "total_of_consignments": null,
        "type": "AGENT_DIRECT",
        "total": null,
        "external_code": null,
        "external_code1": null,
        "external_code2": null,
        "max_length": null,
        "max_width": null,
        "max_depth": null,
        "handling_fee_first_item": null,
        "handling_fee_other_item": null,
        "handling_fee_first_product": null,
        "handling_fee_other_product": null,
        "handling_fee": null,
        "handling_fee_urgent_consignment": null,
        "handling_fee_limit": null,
        "delivery_fee": null,
        "delivery_fee_type": null,
        "return_consignment_id": null,
        "return_consignment_action_type": null,
        "return_consignment_action_name": null,
        "quantity": null,
        "total_price_customs_export_internal": null,
        "battery_type_name_list": null,
        "delivery_service_name": null,
        "sku_count": null,
        "product_company_ref": null,
        "id": 1904090360000032,
        "company_id": 36,
        "client_id": 47,
        "warehouse_id": null,
        "consignment_product_quantity": "0",
        "consignment_product_reference": null,
        "delivery_service_id": 2667,
        "delivery_service_id_internal": 2667,
        "delivery_package_size_id": 741,
        "delivery_package_size_id_internal": 741,
        "total_price": "0.00",
        "total_cost": "0.000",
        "total_delivery_fee": "0.00",
        "total_delivery_cost": "0.000",
        "total_handling_fee": "0.00",
        "total_handling_cost": "0.000",
        "total_weight": "0.00",
        "total_volume": "0.00",
        "total_volume_weight": "0.0000",
        "actual_cost": "0.000",
        "guarantee_percentage": "0.00",
        "contact": "Paul Mcquaid",
        "business_name": null,
        "address_line1": "Penmarric Parish Rd",
        "address_line2": null,
        "address_line3": null,
        "city": "Minster On Sea",
        "county": "Kent",
        "post_code": "ME12 3NG",
        "country_iso": "GB",
        "telephone": "07887 567217",
        "email": null,
        "sender_contact": null,
        "sender_business_name": null,
        "sender_address_line1": null,
        "sender_address_line2": null,
        "sender_address_line3": null,
        "sender_city": null,
        "sender_county": null,
        "sender_post_code": null,
        "sender_country_iso": "GB",
        "sender_email": null,
        "sender_telephone": null,
        "sales_reference": null,
        "customs_price": "0.000",
        "sales_price": "0.000",
        "sales_order_id": null,
        "custom_identity_reference": null,
        "payment_reference": null,
        "delivery_reference": "",
        "tracking_reference": null,
        "special_instruction": null,
        "neighbour_instruction": null,
        "temp_consignment_info_id": null,
        "is_urgent": "0",
        "is_forced_delivery_service": "0",
        "create_time": "2019-04-10 00:07:45",
        "finish_time": null,
        "arrive_time": null,
        "update_time": "2019-04-10 00:07:45",
        "status": "PREPARING",
        "stock_status": "ONLY_ORI_STOCK_ENOUGH",
        "primary_keys": [
            "id"
        ]
    },
    "success": true,
    "moduleName": "client"
}

注意data中的id, 为订单id

添加产品

地址: POST http://test.birdsystem.com/client/Agent-Direct-Consignment-Product/

参数

//订单id
consignment_id=1904090360000032
//产品名称
product_name=light
//产品中文名称
product_name_cn=灯
//客户sku
client_ref=47
//报关价 美元
price_customs_export=1
//重量 g(随系统设置)
weight=20
//数量
quantity=1
//海关属性,用数组提交
product_customs_property[]=17
product_customs_property[]=9


返回

{
    "data": {
        "id": 32699,
        "consignment_id": 1904090360000032,
        "product_name": "light",
        "product_name_cn": "灯",
        "client_ref": "47",
        "quantity": "1",
        "weight": "20.00",
        "price_customs_export": "1.000",
        "price_customs_export_internal": "1.000",
        "primary_keys": [
            "id"
        ]
    },
    "success": true,
    "moduleName": "client"
}


修改状态

修改状态到待处理, 等待仓库处理

地址: POST http://test.birdsystem.com/client/Consignment/Batch-Update-Status/

参数

//订单id, 多个订单用","隔开
ids=1707060110000025
//状态: PENDING为待处理
status=PENDING

返回

{
    "success":true,
    "refresh":false,
    "moduleName":"client"
}