51tracking-sdk-go

The Go SDK of 51Tracking API

Contact: service@51tracking.org

Official document

Document

Index

1. Installation
2. Testing
3. Error Handling
4. SDK
   1. Couriers
   2. Trackings
   3. Air Waybill

Installation

51tracking-sdk-go 要求 Go 版本支持 模块，并使用导入版本控制。因此，请确保在安装 51tracking-sdk-go 之前初始化 Go 模块：

go mod init github.com/my/repo
go get github.com/51tracking/51tracking-sdk-go

插件引入:

import "github.com/51tracking/51tracking-sdk-go"

Quick Start

package main

import (
   "context"
   "fmt"
   "github.com/51tracking/51tracking-sdk-go"
)

func main() {
   key := "you api key"
   cli, err := tracking51.NewClient(key)

   if err != nil {
      fmt.Println(err)
      return
   }

   result, err := cli.GetAllCouriers(context.Background())
   if err != nil {
      fmt.Println(err)
      return
   }

   fmt.Println(result)

   var couriers, ok = result.Data.(*[]tracking51.Courier)
   if !ok {
      fmt.Println("Structure type conversion failed")
      return
   }
   for _, item := range *couriers {
      fmt.Printf("courier_name:%s courier_code:%s\n", item.CourierName, item.CourierCode)
   }
}

Testing

go test

Error handling

Throw by the new SDK client

cli, err := tracking51.NewClient("")

if err != nil {
fmt.Println(err)
return
}

/*
API Key is missing
*/

Throw by the parameter validation in function

cli, err := tracking51.NewClient("you api key")

if err != nil {
   fmt.Println(err)
   return
}

params := tracking51.CreateTrackingParams{
   TrackingNumber: "",
   CourierCode:    "usps",
}
result, err := cli.CreateTracking(context.Background(), params)
if err != nil {
   fmt.Println(err)
   return
}

/*
Tracking number cannot be empty
*/

Examples

Couriers

返回所有支持的快递公司列表

https://api.51Tracking.com/v4/couriers/all

result, err := cli.GetAllCouriers(context.Background())
if err != nil {
  fmt.Println(err)
  return
}

fmt.Println(result)

Trackings

单个物流单号实时添加且查询

https://api.51Tracking.com/v4/trackings/create

params := tracking51.CreateTrackingParams{
  TrackingNumber: "9400111899562537683144",
  CourierCode:    "usps",
}

result, err := cli.CreateTracking(context.Background(), params)
if err != nil {
  fmt.Println(err)
  return
}

fmt.Println(result)

获取多个物流单号的查询结果

https://api.51Tracking.com/v4/trackings/get

currentTime := time.Now()
zeroTime := currentTime.UTC()
layout := "2006-01-02T15:04:05-07:00"
formattedTime := zeroTime.Format(layout)
params := tracking51.GetTrackingResultsParams{
   TrackingNumbers: "92612903029511573030094531,9400111899562539126562",
   CourierCode:     "usps",
   CreatedDateMin: "2023-08-23T06:00:00+00:00",
   CreatedDateMax: formattedTime,
}

result, err := cli.GetTrackingResults(context.Background(), params)
if err != nil {
  fmt.Println(err)
  return
}

fmt.Println(result)

添加多个物流单号（一次调用最多创建 40 个物流单号）

https://api.51Tracking.com/v4/trackings/batch

params := []tracking51.CreateTrackingParams{
  {
      TrackingNumber: "92632903279511573030094832",
      CourierCode:    "usps",
  },
  {
      TrackingNumber: "92642903289511563030094932",
      CourierCode:    "usps",
  },
}

result, err := cli.BatchCreateTrackings(context.Background(), params)
if err != nil {
  fmt.Println(err)
  return
}

fmt.Println(result)

根据ID更新物流信息

https://api.51Tracking.com/v4/trackings/update/{id}

params := tracking51.UpdateTrackingParams{
   CustomerName: "New name",
   Note:         "New tests order note",
}

idString := "9a1d3844a50f3851e76e3ee347881588"
result, err := cli.UpdateTrackingByID(context.Background(), idString, params)
if err != nil {
   fmt.Println(err)
   return
}

fmt.Println(result)

通过ID删除单号

https://api.51Tracking.com/v4/trackings/delete/{id}

idString := "9a1d3844a50f3851e76e3ee347881588"
result, err := cli.DeleteTrackingByID(context.Background(), idString)
if err != nil {
   fmt.Println(err)
   return
}

fmt.Println(result)

通过ID重新查询过期的单号

https://api.51Tracking.com/v4/trackings/retrack/{id}

idString := "99ff2ce10105aeb8627ec0c03e1773bd"
result, err := cli.RetrackTrackingByID(context.Background(), idString)
if err != nil {
   fmt.Println(err)
   return
}

fmt.Println(result)

Air Waybill

查询航空运单的结果

https://api.51Tracking.com/v4/awb

params := tracking51.AirWaybillParams{
AwbNumber: "235-69030430",
}

result, err := cli.CreateAnAirWayBill(context.Background(), params)
if err != nil {
fmt.Println(err)
return
}

fmt.Println(result)

响应状态码

51Tracking 使用传统的HTTP状态码来表明 API 请求的状态。通常，2xx形式的状态码表示请求成功，4XX形式的状态码表请求发生错误（比如：必要参数缺失），5xx格式的状态码表示 51tracking 的服务器可能发生了问题。

Http CODE	META CODE	TYPE	MESSAGE
200	200	成功	请求响应成功。
400	400	错误请求	请求类型错误。请查看 API 文档以了解此 API 的请求类型。
400	4101	错误请求	物流单号已存在。
400	4102	错误请求	物流单号不存在。请先使用「Create接口」将单号添加至系统。
400	4103	错误请求	您已超出 API 调用的创建数量。每次创建的最大数量为 40 个快递单号。
400	4110	错误请求	物流单号(tracking_number) 不符合规则。
400	4111	错误请求	物流单号(tracking_number)为必填字段。
400	4112	错误请求	查询ID无效。
400	4113	错误请求	不允许重新查询。您只能重新查询过期的物流单号。
400	4120	错误请求	物流商简码(courier_code)的值无效。
400	4121	错误请求	无法识别物流商。
400	4122	错误请求	特殊物流商字段缺失或填写不符合规范。
400	4130	错误请求	请求参数的格式无效。
400	4160	错误请求	空运单号(awb_number)是必需的或有效的格式。
400	4161	错误请求	此空运航空不支持查询。
400	4165	错误请求	查询失败：未创建空运单号。
400	4166	错误请求	删除未创建的空运单号失败。
400	4167	错误请求	空运单号已存在，无需再次创建。
400	4190	错误请求	当前查询额度不足。
401	401	未经授权	身份验证失败或没有权限。请检查并确保您的 API 密钥正确无误。
403	403	禁止	禁止访问。请求被拒绝或不允许访问。
404	404	未找到	页面不存在。请检查并确保您的链接正确无误。
429	429	太多请求	超出 API 请求限制，请稍后重试。请查看 API 文档以了解此 API 的限制。
500	511	服务器错误	服务器错误。请联系我们： service@51Tracking.org。
500	512	服务器错误	服务器错误。请联系我们：service@51Tracking.org。
500	513	服务器错误	服务器错误。请联系我们： service@51Tracking.org。