Skip to content

Commit 1772bdc

Browse files
liaohanfeiliaohanfei
committed
first commit
1 parent 9e68af2 commit 1772bdc

39 files changed

+2068
-1
lines changed

‎.gitignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# NuGet packages
2+
## This ignores all NuGet packages, including the packages/ directory in the solution root.
3+
**/packages/
4+
5+
# User-specific files
6+
## Visual Studio files
7+
.vscode/
8+
*.suo
9+
*.user
10+
*.userosscache
11+
*.sln.docstates
12+
13+
## User-specific files
14+
*.suo
15+
*.user
16+
*.userosscache
17+
*.sln.docstates
18+
19+
# Mono Auto Generated Files
20+
mono_crash.*
21+
22+
# Windows image file caches
23+
Thumbs.db
24+
ehthumbs.db
25+
26+
# Folder config file
27+
Desktop.ini
28+
29+
# Recycle Bin used on file shares
30+
$RECYCLE.BIN/
31+
32+
# VS Code directories
33+
.vscode/
34+
35+
# Windows Installer files
36+
*.cab
37+
*.msi
38+
*.msm
39+
*.msp
40+
41+
# Windows shortcuts
42+
*.lnk
43+
44+
# JetBrains Rider
45+
.idea/
46+
47+
# User-specific files
48+
*.suo
49+
*.user
50+
*.userosscache
51+
*.sln.docstates
52+
53+
# Others
54+
bin/
55+
obj/

‎README.md‎

Lines changed: 301 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,302 @@
1-
# trackingmore-sdk-net
1+
trackingmore-sdk-net
2+
=================
3+
24
The .Net SDK of Trackingmore API
5+
6+
Contact: <manage@trackingmore.org>
7+
8+
## Official document
9+
10+
[Document](https://www.trackingmore.com/docs/trackingmore/d5ac362fc3cda-api-quick-start)
11+
12+
## Index
13+
1. [Installation](https://github.com/TrackingMores/trackingmore-sdk-net#installation)
14+
2. [Testing](https://github.com/TrackingMores/trackingmore-sdk-net#testing)
15+
3. [Error Handling](https://github.com/TrackingMores/trackingmore-sdk-net#error-handling)
16+
4. SDK
17+
1. [Couriers](https://github.com/TrackingMores/trackingmore-sdk-net#couriers)
18+
2. [Trackings](https://github.com/TrackingMores/trackingmore-sdk-net#trackings)
19+
3. [Air Waybill](https://github.com/TrackingMores/trackingmore-sdk-net#air-waybill)
20+
21+
22+
## Installation
23+
24+
```
25+
$ dotnet add package trackingmore
26+
```
27+
28+
## Quick Start
29+
30+
```c#
31+
using TrackingMoreAPI.Model.Couriers;
32+
using TrackingMoreAPI.Model.AirWaybills;
33+
using TrackingMoreAPI.Model.Trackings;
34+
using TrackingMoreAPI.Model;
35+
36+
namespace TrackingMoreAPI;
37+
38+
public class Test
39+
{
40+
41+
static void Main(string[] args)
42+
{
43+
try
44+
{
45+
string apiKey = "you api key";
46+
TrackingMore trackingMore = new TrackingMore(apiKey);
47+
48+
var apiResponse = trackingMore.Courier.GetAllCouriers();
49+
Console.WriteLine(apiResponse.meta.code);
50+
foreach (var item in apiResponse.data)
51+
{
52+
Console.WriteLine("courierName: " + item.courierName);
53+
Console.WriteLine("courierCode: " + item.courierCode);
54+
Console.WriteLine();
55+
}
56+
}
57+
catch (TrackingMoreException ex)
58+
{
59+
Console.WriteLine("Catch custom exceptions：" + ex.Message);
60+
}
61+
catch (Exception ex)
62+
{
63+
Console.WriteLine("Catch other exceptions:" + ex.Message);
64+
}
65+
66+
}
67+
68+
}
69+
```
70+
71+
## Testing
72+
73+
In the root directory of the test project, run the following command to execute the test
74+
```
75+
dotnet test
76+
```
77+
78+
## Error handling
79+
80+
**Throw** by the new SDK client
81+
82+
```c#
83+
try
84+
{
85+
string apiKey = "";
86+
TrackingMore trackingMore = new TrackingMore(apiKey);
87+
}
88+
catch (TrackingMoreException ex)
89+
{
90+
Console.WriteLine("Catch custom exceptions：" + ex.Message);
91+
}
92+
93+
# API Key is missing
94+
```
95+
96+
**Throw** by the parameter validation in function
97+
98+
```c#
99+
try
100+
{
101+
string apiKey = "you api key";
102+
TrackingMore trackingMore = new TrackingMore(apiKey);
103+
104+
DetectParams detectParams = new DetectParams();
105+
detectParams.trackingNumber = "";
106+
var apiResponse = trackingMore.Courier.detect(detectParams);
107+
}
108+
catch (TrackingMoreException ex)
109+
{
110+
Console.WriteLine("Catch custom exceptions：" + ex.Message);
111+
}
112+
113+
# Tracking number cannot be empty
114+
```
115+
## Examples
116+
117+
## Couriers
118+
##### Return a list of all supported couriers.
119+
https://api.trackingmore.com/v4/couriers/all
120+
```c#
121+
var apiResponse = trackingMore.Courier.GetAllCouriers();
122+
Console.WriteLine(apiResponse.meta.code);
123+
foreach (var item in apiResponse.data)
124+
{
125+
Console.WriteLine("courierName: " + item.courierName);
126+
Console.WriteLine("courierCode: " + item.courierCode);
127+
Console.WriteLine();
128+
}
129+
```
130+
131+
##### Return a list of matched couriers based on submitted tracking number.
132+
https://api.trackingmore.com/v4/couriers/detect
133+
```c#
134+
DetectParams detectParams = new DetectParams();
135+
detectParams.trackingNumber = "9261290306531704519171";
136+
var apiResponse = trackingMore.Courier.detect(detectParams);
137+
Console.WriteLine(apiResponse.meta.code);
138+
foreach (var item in apiResponse.data)
139+
{
140+
Console.WriteLine("courierName: " + item.courierName);
141+
Console.WriteLine("courierCode: " + item.courierCode);
142+
143+
Console.WriteLine();
144+
}
145+
```
146+
147+
## Trackings
148+
##### Create a tracking.
149+
https://api.trackingmore.com/v4/trackings/create
150+
```c#
151+
CreateTrackingParams createTrackingParams = new CreateTrackingParams();
152+
createTrackingParams.trackingNumber = "9261290306531704519171";
153+
createTrackingParams.courierCode = "usps";
154+
var apiResponse = trackingMore.Tracking.CreateTracking(createTrackingParams);
155+
Console.WriteLine(apiResponse.meta.code);
156+
Console.WriteLine(apiResponse.data.trackingNumber);
157+
Console.WriteLine(apiResponse.data.courierCode);
158+
159+
```
160+
161+
##### Get tracking results of multiple trackings.
162+
https://api.trackingmore.com/v4/trackings/get
163+
```c#
164+
GetTrackingResultsParams getTrackingResultsParams = new GetTrackingResultsParams();
165+
// getTrackingResultsParams.trackingNumbers = "9261290306531704519171,92612903029511573030094547";
166+
// getTrackingResultsParams.courierCode = "usps";
167+
getTrackingResultsParams.createdDateMin = "2023-10-09T06:00:00+00:00";
168+
getTrackingResultsParams.createdDateMax = "2023-10-10T13:45:00+00:00";
169+
var apiResponse = trackingMore.Tracking.GetTrackingResults(getTrackingResultsParams);
170+
Console.WriteLine(apiResponse.meta.code);
171+
foreach (var item in apiResponse.data)
172+
{
173+
Console.WriteLine("trackingNumber: " + item.trackingNumber);
174+
Console.WriteLine("courierCode: " + item.courierCode);
175+
176+
Console.WriteLine();
177+
}
178+
```
179+
180+
##### Create multiple trackings (Max. 40 tracking numbers create in one call).
181+
https://api.trackingmore.com/v4/trackings/batch
182+
```c#
183+
List<CreateTrackingParams> trackingParamsList = new List<CreateTrackingParams>();
184+
185+
CreateTrackingParams trackingParams1 = new CreateTrackingParams
186+
{
187+
trackingNumber = "9261290306531704519172",
188+
courierCode = "usps"
189+
};
190+
191+
trackingParamsList.Add(trackingParams1);
192+
193+
CreateTrackingParams trackingParams2 = new CreateTrackingParams
194+
{
195+
trackingNumber = "9261290306531704519174",
196+
courierCode = "usps"
197+
};
198+
199+
trackingParamsList.Add(trackingParams2);
200+
var apiResponse = trackingMore.Tracking.BatchCreateTrackings(trackingParamsList);
201+
Console.WriteLine(apiResponse.meta.code);
202+
foreach (var item in apiResponse.data.success)
203+
{
204+
Console.WriteLine("trackingNumber: " + item.trackingNumber);
205+
Console.WriteLine("courierCode: " + item.courierCode);
206+
207+
Console.WriteLine();
208+
}
209+
210+
foreach (var item in apiResponse.data.error)
211+
{
212+
Console.WriteLine("trackingNumber: " + item.trackingNumber);
213+
Console.WriteLine("courierCode: " + item.courierCode);
214+
215+
Console.WriteLine();
216+
}
217+
```
218+
219+
##### Update a tracking by ID.
220+
https://api.trackingmore.com/v4/trackings/update/{id}
221+
```c#
222+
UpdateTrackingParams updateTrackingParams = new UpdateTrackingParams();
223+
updateTrackingParams.customerName = "New name";
224+
updateTrackingParams.note = "New tests order note";
225+
string idString = "9a557acc90dd57df78933fcc09ab9657";
226+
var apiResponse = trackingMore.Tracking.UpdateTrackingByID(idString, updateTrackingParams);
227+
Console.WriteLine(apiResponse.meta.code);
228+
if(apiResponse.data != null){
229+
Console.WriteLine(apiResponse.data.trackingNumber);
230+
Console.WriteLine(apiResponse.data.courierCode);
231+
Console.WriteLine(apiResponse.data.customerName);
232+
Console.WriteLine(apiResponse.data.note);
233+
}
234+
```
235+
236+
##### Delete a tracking by ID.
237+
https://api.trackingmore.com/v4/trackings/delete/{id}
238+
```c#
239+
string idString = "9a5575a8b14833ff3a34d357709707b7";
240+
var apiResponse = trackingMore.Tracking.RetrackTrackingByID(idString);
241+
Console.WriteLine(apiResponse.meta.code);
242+
if(apiResponse.data != null){
243+
Console.WriteLine(apiResponse.data.trackingNumber);
244+
Console.WriteLine(apiResponse.data.courierCode);
245+
}
246+
```
247+
248+
##### Retrack expired tracking by ID.
249+
https://api.trackingmore.com/v4/trackings/retrack/{id}
250+
```c#
251+
string idString = "9a5575a8b14833ff3a34d357709707b7";
252+
var apiResponse = trackingMore.Tracking.RetrackTrackingByID(idString);
253+
Console.WriteLine(apiResponse.meta.code);
254+
if(apiResponse.data != null){
255+
Console.WriteLine(apiResponse.data.trackingNumber);
256+
Console.WriteLine(apiResponse.data.courierCode);
257+
}
258+
```
259+
## Air Waybill
260+
##### Create an air waybill.
261+
https://api.trackingmore.com/v4/awb
262+
```c#
263+
AirWaybillParams airWaybillParams = new AirWaybillParams();
264+
airWaybillParams.awbNumber = "235-69030430";
265+
var apiResponse = trackingMore.AirWaybill.CreateAnAirWayBill(airWaybillParams);
266+
Console.WriteLine(apiResponse.meta.code);
267+
Console.WriteLine(apiResponse.data.awbNumber);
268+
Console.WriteLine(apiResponse.data.flightInfoNew[0].flightNumber);
269+
Console.WriteLine(apiResponse.data.flightInfo["TK0721"].departStation);
270+
271+
```
272+
273+
## Response Code
274+
275+
Trackingmore uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an TrackingMore's server error.
276+
277+
278+
Http CODE|META CODE|TYPE | MESSAGE
279+
----|-----|--------------|-------------------------------
280+
200 |200 | <code>Success</code> | Request response is successful
281+
400 |400 | <code>BadRequest</code> | Request type error. Please check the API documentation for the request type of this API.
282+
400 |4101 | <code>BadRequest</code> | Tracking No. already exists.
283+
400 |4102 | <code>BadRequest</code> | Tracking No. no exists. Please use 「Create a tracking」 API first to create shipment.
284+
400 |4103 | <code>BadRequest</code> | You have exceeded the shipment quantity of API call. The maximum quantity is 40 shipments per call.
285+
400 |4110 | <code>BadRequest</code> | The value of tracking_number is invalid.
286+
400 |4111 | <code>BadRequest</code> | Tracking_number is required.
287+
400 |4112 | <code>BadRequest</code> | Invalid Tracking ID.
288+
400 |4113 | <code>BadRequest</code> | Retrack is not allowed. You can only retrack an expired tracking.
289+
400 |4120 | <code>BadRequest</code> | The value of courier_code is invalid.
290+
400 |4121 | <code>BadRequest</code> | Cannot detect courier.
291+
400 |4122 | <code>BadRequest</code> | Missing or invalid value of the special required fields for this courier.
292+
400 |4130 | <code>BadRequest</code> | The format of Field name is invalid.
293+
400 |4160 | <code>BadRequest</code> | The awb_number is required or invaild format.
294+
400 |4161 | <code>BadRequest</code> | The awb airline does not support yet.
295+
400 |4190 | <code>BadRequest</code> | You are reaching the maximum quota limitation, please upgrade your current plan.
296+
401 |401 | <code>Unauthorized</code> | Authentication failed or has no permission. Please check and ensure your API Key is correct.
297+
403 |403 | <code>Forbidden</code> | Access prohibited. The request has been refused or access is not allowed.
298+
404 |404 | <code>NotFound</code> | Page does not exist. Please check and ensure your link is correct.
299+
429 |429 | <code>TooManyRequests</code>| Exceeded API request limits, please try again later. Please check the API documentation for the limit of this API.
300+
500 |511 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.
301+
500 |512 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.
302+
500 |513 | <code>ServerError</code> | Server error. Please contact us: service@trackingmore.org.

‎Test/GlobalUsings.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
global using Xunit;

‎Test/Test.csproj‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net7.0</TargetFramework>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<Nullable>enable</Nullable>
7+
8+
<IsPackable>false</IsPackable>
9+
<IsTestProject>true</IsTestProject>
10+
</PropertyGroup>
11+
12+
<ItemGroup>
13+
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.7.1" />
14+
<PackageReference Include="xunit" Version="2.4.2" />
15+
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
16+
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
17+
<PrivateAssets>all</PrivateAssets>
18+
</PackageReference>
19+
<PackageReference Include="coverlet.collector" Version="3.2.0">
20+
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
21+
<PrivateAssets>all</PrivateAssets>
22+
</PackageReference>
23+
</ItemGroup>
24+
25+
<ItemGroup>
26+
<ProjectReference Include="..\TrackingMoreAPI\TrackingMoreAPI.csproj" />
27+
</ItemGroup>
28+
29+
</Project>

0 commit comments

Comments
 (0)