DeftShip 授权及发货

一、地址相关

登录地址：https://app.deftship.com/en/login
生产环境域名：https://deftship.com/api
沙箱环境域名：https://sandbox.deftship.com/api
API文档：登录之后，点击api，进入如下页面，点击API docs进入api文档界面

二、授权获取Token

1.创建沙箱或者生产环境

点击之后出现如下界面

Name: 自定义名称
Webhook Endpoint : 回调接口路径，这里是项目中自定义接口。需要你提供给DeftShip

2.生成token之后需要复制保存下来，只会出现一次

3.如何使用

请求头添加token即可

三.创建发货单

1.校验地址是否可用（可选择是否使用）

主要是防止在创建发货单时报错地址不可用，相当于前置校验。接口 /address/validate
请求实体类

@Data
public class ValidateAddressRequest {
    private String attention;
    private String name;
    private String street_1;
    private String street_2;
    private String street_3;
    private String city;
    private String zip;
    private String state;
    private String country;
    private String telephone;
}

响应实体

public class ValidateAddressResponse {
    private Boolean success;
    private String message;
    private Object data;
}

2.发货

根据自身业务需求，是先创建发货单，再由人工发货。还是直接由系统发。
这里介绍如何直接通过系统直接发出

1.获取费率(先调用此接口，计算费率。/parcel-orders/get-rates)
请求实体，此处请求实体与调用创建发货单参数一致(/parcel-orders)

public class CreateParcelRequest {
    /**
     * This field is used to identify sender address. You can fetch your saved addresses from address-book. Addresses can be managed from the website on live dashboard or sandbox dashboard. Not required if a "from_address" object was used.
     *
     * Note: If both "from_address_id" and "from_address" fields are defined system will prioritise the "from_address_id".
     * deftship地址本上存储的地址id，如果传了此id可不填发件人信息
     */
    private Integer from_address_id;

    /**
     * 	This field is used to identify return address. You should use the address which is in your saved from addresses. You can fetch your saved from addresses from address-book. Addresses can be managed from the website on live dashboard or sandbox dashboard.
     *  deftship地址本上存储的地址id，如果传了此id可不填收件人信息
     */
    private Integer return_address_id;


    /**
     * 发货地址信息
     */
    private FromAddress from_address;

    /**
     * 收件人地址信息
     */
    private ToAddress to_address;

    /**
     * 包裹信息
     */
    private List<PackageVo> package_list;

    public CreateParcelRequest() {
        this.from_address = new FromAddress();
        this.to_address = new ToAddress();
    }

    /**
     * 发件人信息
     */
    @Data
    public static class FromAddress{
        private String name;
        private String attention;
        private String street_1;
        private String street_2;
        private String street_3;
        private String city;
        private String zip;
        private String state;
        private String country;
        private String telephone;
    }

    /**
     * 收件人信息
     */
    @Data
    public static class ToAddress{
        private String name;
        private String attention;
        private String street_1;
        private String street_2;
        private String street_3;
        private String city;
        private String zip;
        private String state;
        private String country;
        private String telephone;
    }

    /**
     * 包裹信息
     */
    @Data
    public static class PackageVo{
        private Integer count;
        private String box_type;
        private Float length;
        private Float width;
        private Float height;
        private Float weight;
        private String reference_2;
        private Boolean insurance;
        private List<String> signature;
        private List<DeftShipCreateParcelItem> items ;

        /**
         * 包裹明细信息
         */
        @Data
        public static class DeftShipCreateParcelItem{
            private Integer quantity;
            private Float price;
            private Float country_of_manufacture;
            private String sku;
            private String description;
            private String content_type;
       }
    }


}

响应

@Data
public class GetRatesResponse implements Serializable {
    private Boolean success;
    private String message;
    private List<CarrierDto> data;

    @Data
    public static class CarrierDto{
        private Integer id;
        private String carrier;
        private String service;
        private String service_code;
        private Float final_price;
        private Float fuel_price;
//        private List<String> restrictions;
//        private List<Float> miscellaneous_charges;
        private String freight_class;
        private Boolean has_enough_credits;
    }
}

这里包含多个报价信息，看自身业务取哪个。这里的id就是发货要用到的参数rate_id

2.调用发货接口，进行发货（/parcel-orders/ship）
请求参数如上，只有一个rate_id
响应

@Data
public class SendParcelResponse {
    private Boolean success;
    private String message;
    private Object data;
}

这个data的字段如下。

{
    "shipment_order_id": 123123123,
    "main_tracking_number": "1Z47D7YDHBEG123",
    "sub_tracking_numbers": ["1Z47D7YDHBEG123", "1Z47D7YDHBEG124"],
    "package_details": [
        {
            "tracking_number": "1Z5RR1050313482583",
            "items": [
                {
                    "sku": "SKU1",
                    "quantity": "1",
                    "price": "1.00"
                },
                {
                    "sku": "SKU2",
                    "quantity": "2",
                    "price": "2.00"
                }
            ]
        }
    ],
    "final_price": "11.11",
    "carrier": "ups",
    "service": "UPS® Ground",
    "label": "/label/url/12355",
    "customs_form": "/customs/url/123123"
}

取消发货单（/freight-orders/void）

请求参数，就是发货之后的发货单号。上面可以看到有返回

@Data
public class VoidParcelRequest {
    private Integer shipment_order_id;
}

响应

@Data
public class VoidParcelResponse {
    private Boolean success;
    private String message;
    private Object data;
}

总结

本文主要介绍授权、发货、取消发货功能。其余功能请参考API文档。