xpo

README

xpologistics

Golang Code to Work With the XPO Logistics API

Documentation

Overview

Package xpo provides tooling to connect to the XPO Logistics API. This is for truck shipments, not small parcels. Think LTL (less than truckload) shipments. This code was created off the XPO API documentation.

The XPO API requires two steps in making the first request per usage. The first request gets a "bearer" token which is used in following requests that actually do something (like scheduling a pickup). Why the API is designed this way, who knows, but it is dumb. The "bearer" token is valid for 12 hours so you can reuse it and thus only have to make one request for future requests (up until 12 hours from the initial request that got the "bearer" token).

Currently this package can perform: - pickup requests

To create a pickup request: - Set test or production mode (SetProductionMode()). - Set your shipper (Shipper{}) and requestor (Requestor{}) info. - Set shipment details (PkupItem{}). - Request the pickup (RequestPickup()). - Check for any errors.

Index

• Variables
• func SetCredentials(u, p, t string)
• func SetProductionMode(yes bool)
• func SetTimeout(seconds time.Duration)
• type ConfirmationNumber
• type Contact
• type Email
• type ErrorPickupResponse
• type Phone
• type PickupRequest
• type PickupRqstInfo
  • func (pri *PickupRqstInfo) RequestPickup() (response SuccessfulPickupResponse, err error)
• type PkupItem
• type Requestor
• type Shipper
• type SuccessfulPickupResponse
• type TokenResponse
• type Weight

Variables

var (
	RoleShipper    = "S"
	RoleConsignee  = "C"
	RoleThirdParty = "3"
)

role codes for what the requestor of the pickup is in relation to this shipment

Functions

func SetCredentials

func SetCredentials(u, p, t string)

SetCredentials saves our XPO username, password, access token for use later.

func SetProductionMode

func SetProductionMode(yes bool)

SetProductionMode chooses the production url for use

func SetTimeout

func SetTimeout(seconds time.Duration)

SetTimeout updates the timeout value to something the user sets use this to increase the timeout if connecting to XPO is really slow

Types

type ConfirmationNumber

type ConfirmationNumber struct {
	PickupID        string `json:"pickupId"`
	ConfirmationNbr string `json:"confirmationNbr"` //pickup confirmation number
}

ConfirmationNumber holds the actual pickup request number

type Contact

type Contact struct {
	CompanyName string `json:"companyName"`
	Email       Email  `json:"email"`
	FullName    string `json:"fullName"`
	Phone       Phone  `json:"phone"`
}

Contact holds contact information

type Email

type Email struct {
	EmailAddr string `json:"emailAddr"`
}

Email holds an email address why this is a separate struct...ask XPO

type ErrorPickupResponse

type ErrorPickupResponse struct {
	XMLName     xml.Name `xml:"fault"`
	Code        string   `xml:"code"`
	Type        string   `xml:"type"`
	Message     string   `xml:"message"`
	Description string   `xml:"description"`
}

ErrorPickupResponse is the data returned when a pickup cannot be scheduled XPO API takes in JSON but returns XML upon error each field starts with "am:" but that can be excluded from struct tags

type Phone

type Phone struct {
	PhoneNbr string `json:"phoneNbr"` //format is 999-999999
}

Phone holds an phone number why this is a separate struct...ask XPO

type PickupRequest

type PickupRequest struct {
	PickupRqstInfo PickupRqstInfo `json:"pickupRqstInfo"`
}

PickupRequest is the main container struct for data sent to XPO to request a pickup This is a single field with another container struct inside. Why...who knows, ask XPO.

type PickupRqstInfo

type PickupRqstInfo struct {
	//required
	PkupDate  string     `json:"pkupDate"`  //YYYY-MM-DDTHH:MM:SS
	ReadyTime string     `json:"readyTime"` //YYYY-MM-DDTHH:MM:SS
	CloseTime string     `json:"closeTime"` //YYYY-MM-DDTHH:MM:SS
	PkupItem  []PkupItem `json:"pkupItem"`  //items being picked up, up to 50

	//optional
	SpecialEquipmentCd string    `json:"specialEquipmentCd"`
	InsidePkupInd      bool      `json:"insidePkupInd"`
	Shipper            Shipper   `json:"shipper"`
	Requestor          Requestor `json:"requestor"`
	Contact            Contact   `json:"contact"` //usually same as requestor.contact
	Remarks            string    `json:"remarks"` //any random note
	TotPalletCnt       uint      `json:"totPalletCnt"`
	TotLoosePieceCnt   uint      `json:"totLoosePieceCnt"`
	TotWeight          Weight    `json:"totWeight"`
}

PickupRqstInfo holds all the data on a pickup request

func (*PickupRqstInfo) RequestPickup

func (pri *PickupRqstInfo) RequestPickup() (response SuccessfulPickupResponse, err error)

RequestPickup performs the API call to schedule a pickup requests to XPO require two steps: getting a token, and making the pickup request. Why? b/c dumb.

type PkupItem

type PkupItem struct {
	//required
	TotWeight Weight `json:"totWeight"`

	//optional
	DestZip6       string `json:"destZip6"` //ship to zip/postal code
	LoosePiecesCnt uint   `json:"loosePiecesCnt"`
	PalletCnt      uint   `json:"palletCnt"`
	GarntInd       bool   `json:"garntInd"` //guaranteed service
	HazmatInd      bool   `json:"hazmatInd"`
	FrzbleInd      bool   `json:"frzbleInd"`
	HolDlvrInd     bool   `json:"holDlvrInd"`    //holiday or weekend delivery requested
	FoodInd        bool   `json:"foodInd"`       //food stuffs
	BulkLiquidInd  bool   `json:"bulkLiquidInd"` //bulk liquid shipment greater than 119 US gallons
	Remarks        string `json:"remarks"`       //random note for this pickup
}

PkupItem is the good being picked up

type Requestor

type Requestor struct {
	Contact Contact `json:"contact"`
	RoleCd  string  `json:"roleCd"` //"S" for shipper, "C" for consignee, "3" for third party
}

Requestor holds data on who requested the pickup

type Shipper

type Shipper struct {
	//required
	AddressLine1 string `json:"addressLine1"`
	CityName     string `json:"cityName"`
	StateCd      string `json:"stateCd"`   //two character code
	CountryCd    string `json:"countryCd"` //to char code

	//optional
	Name         string `json:"name"` //company name
	AddressLine2 string `json:"addressLine2"`
	PostalCd     string `json:"postalCd"`
	Phone        Phone  `json:"phone"`
}

Shipper holds data on the shipper

type SuccessfulPickupResponse

type SuccessfulPickupResponse struct {
	Code                 string             `json:"code"`
	TransactionTimestamp uint64             `json:"transactionTimestamp"` //unix timestamp
	Data                 ConfirmationNumber `json:"data"`
}

SuccessfulPickupResponse is the data returned when a pickup is scheduled

type TokenResponse

type TokenResponse struct {
	BearerToken  string `json:"access_token"`  //not the same as our account access token even though xpo sometimes calls them the same thing
	RefreshToken string `json:"refresh_token"` //some other token, used to get a new pair of bearer & access tokens
	Scope        string `json:"scope"`         //default
	TokenType    string `json:"token_type"`    //Bearer
	ExpiresIn    uint   `json:"expires_in"`    //43200
}

TokenResponse is the data returned when we retrieve the bearer token

type Weight

type Weight struct {
	Weight uint `json:"weight"` //int per XPO
}

Weight holds a weight