-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathshipengine.py
More file actions
200 lines (172 loc) · 9.85 KB
/
Copy pathshipengine.py
File metadata and controls
200 lines (172 loc) · 9.85 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
"""The entrypoint to the ShipEngine API SDK."""
from typing import Any, Dict, List, Union
from shipengine.enums import Endpoints
from .http_client import ShipEngineClient
from .shipengine_config import ShipEngineConfig
class ShipEngine:
config: ShipEngineConfig
"""
Global configuration for the ShipEngine API client, such as timeouts,
retries, page size, etc. This configuration applies to all method calls,
unless specifically overridden when calling a method.
"""
def __init__(self, config: Union[str, Dict[str, Any], ShipEngineConfig]) -> None:
"""
Exposes the functionality of the ShipEngine API.
The `api_key` you pass in can be either a ShipEngine sandbox
or production API Key. (sandbox keys start with "TEST_")
"""
self.client = ShipEngineClient()
if type(config) is str:
self.config = ShipEngineConfig({"api_key": config})
elif type(config) is dict:
self.config = ShipEngineConfig(config)
def create_label_from_rate_id(
self, rate_id: str, params: Dict[str, Any], config: Union[str, Dict[str, Any]] = None
) -> Dict[str, Any]:
"""
When retrieving rates for shipments using the /rates endpoint, the returned information
contains a rateId property that can be used to generate a label without having to refill
in the shipment information repeatedly.
See: https://shipengine.github.io/shipengine-openapi/#operation/create_label_from_rate
:param str rate_id: The rate_id you wish to create a shipping label for.
:param Dict[str, Any] params: A dictionary of label params that will dictate the label
display and level of verification.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: A label that corresponds the to shipment details for the
rate_id provided.
"""
config = self.config.merge(new_config=config)
return self.client.post(endpoint=f"v1/labels/rates/{rate_id}", params=params, config=config)
def create_label_from_shipment(
self, shipment: Dict[str, Any], config: Union[str, Dict[str, Any]] = None
) -> Dict[str, Any]:
"""
Purchase and print a shipping label for a given shipment.
See: https://shipengine.github.io/shipengine-openapi/#operation/create_label
:param Dict[str, Any] shipment: A dictionary of shipment details for the label creation.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: A label that corresponds the to shipment details provided.
"""
config = self.config.merge(new_config=config)
return self.client.post(endpoint="v1/labels", params=shipment, config=config)
def get_rate_estimate(
self, params: Dict[str, Any], config: Union[str, Dict[str, Any]] = None
) -> list[Dict[str, Any]]:
"""
Get a rate estimate for a shipment given a minimal set of shipment details.
Unlike get_rates_from_shipment, this endpoint does not require a full shipment object.
Note: estimates do not include all possible charges (e.g. fuel surcharges, customs fees).
See: https://shipengine.github.io/shipengine-openapi/#operation/estimate_rates
:param Dict[str, Any] params: A dictionary of rate estimate params including carrier_ids,
origin/destination postal codes and country codes, and package weight.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns list[Dict[str, Any]]: A list of rate estimates from the specified carriers.
"""
config = self.config.merge(new_config=config)
return self.client.post(
endpoint=Endpoints.GET_RATE_ESTIMATE.value, params=params, config=config
)
def get_rates_from_shipment(
self, shipment: Dict[str, Any], config: Union[str, Dict[str, Any]] = None
) -> Dict[str, Any]:
"""
Given some shipment details and rate options, this endpoint returns a list of rate quotes.
See: https://shipengine.github.io/shipengine-openapi/#operation/calculate_rates
:param Dict[str, Any] shipment: A dictionary of shipment details for the label creation.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: A label that corresponds the to shipment details provided.
"""
config = self.config.merge(new_config=config)
return self.client.post(
endpoint=Endpoints.GET_RATE_FROM_SHIPMENT.value, params=shipment, config=config
)
def list_carriers(self, config: Dict[str, Any] = None) -> Dict[str, Any]:
"""
Fetch the carrier accounts connected to your ShipEngine Account.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: The carrier accounts associated with a given ShipEngine Account.
"""
config = self.config.merge(new_config=config)
return self.client.get(endpoint=Endpoints.LIST_CARRIERS.value, config=config)
def track_package_by_label_id(
self, label_id: str, config: Dict[str, Any] = None
) -> Dict[str, Any]:
"""
Retrieve a given shipping label's tracking information with a label_id.
See: https://shipengine.github.io/shipengine-openapi/#operation/get_tracking_log_from_label
:param str label_id: The label_id for a shipment you wish to get tracking information for.
(Best option if you create labels via ShipEngine API)
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: Tracking information corresponding to the label_id provided.
"""
config = self.config.merge(new_config=config)
return self.client.get(endpoint=f"v1/labels/{label_id}/track", config=config)
def track_package_by_carrier_code_and_tracking_number(
self, carrier_code: str, tracking_number: str, config: Dict[str, Any] = None
) -> Dict[str, Any]:
"""
Retrieve the label's tracking information with Carrier Code and Tracking Number.
See: https://shipengine.github.io/shipengine-openapi/#operation/get_tracking_log
:param str carrier_code: The carrier_code for the carrier servicing the shipment.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: Tracking information corresponding to the carrier_code and
tracking_number provided.
"""
config = self.config.merge(new_config=config)
return self.client.get(
endpoint=f"v1/tracking?carrier_code={carrier_code}&tracking_number={tracking_number}",
config=config,
)
def validate_addresses(
self, address: List[Dict[str, Any]], config: Union[str, Dict[str, Any]] = None
) -> Dict[str, Any]:
"""
Address validation ensures accurate addresses and can lead to reduced shipping costs
by preventing address correction surcharges. ShipEngine cross references multiple
databases to validate addresses and identify potential deliverability issues.
See: https://shipengine.github.io/shipengine-openapi/#operation/validate_address
:param List[Dict[str, Any]] address: A list containing the address(es) to be validated.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns: Dict[str, Any]: The response from ShipEngine API including the validated
and normalized address.
"""
config = self.config.merge(new_config=config)
return self.client.post(
endpoint=Endpoints.ADDRESSES_VALIDATE.value, params=address, config=config
)
def void_label_by_label_id(
self, label_id: str, config: Union[str, Dict[str, Any]]
) -> Dict[str, Any]:
"""
Void label with a Label Id.
See: https://shipengine.github.io/shipengine-openapi/#operation/void_label
:param str label_id: The label_id of the label you wish to void.
:param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration
to set new values for properties of the global ShipEngineConfig object.
:returns Dict[str, Any]: The response from ShipEngine API confirming the label was
successfully voided or unable to be voided.
"""
config = self.config.merge(new_config=config)
return self.client.put(endpoint=f"v1/labels/{label_id}/void", config=config)
def list_labels_by_tracking_number(
self, tracking_number: str, config: Union[str, Dict[str, Any]] = None
) -> Dict[str, Any]:
"""
Lists labels with the specified tracking_number
:param str tracking_number: The tracking_number of the label(s) you wish to get.
:returns Dict[str, Any]: The response from ShipEngine API including the label(s) with
the specified tracking_number.
"""
config = self.config.merge(new_config=config)
return self.client.get(
endpoint=f"v1/labels?tracking_number={tracking_number}", config=config
)