Rating API Specification
Overview
This API allows the integration of customers’ systems with Maersk Freight Services’ for rating new shipment information from their systems. It can be worked into many customers’ workflows and/or scenarios. Although it’s not required, this step can be taken before calling our Shipment Entry API.
Getting Started
The following functions can be used:
| Function | Description |
|---|---|
| GetNewQuote | Used to get the object needed to be populated and then used as the input parameter to the Rate and RateAllServices functions in this API. |
| GetQuote | Used to get a Quote response gotten previously from the Rate or RateAllServices functions in this API. The QuoteID value that was generated and assigned to the original Quote response is required as an input parameter to this function. |
| SOAP/REST | Used to submit a Quote to Maersk for Rating. This function accepts only one Service code value at a time, and it is recommended to use the RateAllServices function instead to see all Services rated at once for the given Quote data submitted. |
| Rate | Used to submit a Quote to Maersk for Rating. It allows for all Service levels to be rated at once and returned in the response to the caller. It is recommended that this function is used instead of Rate because many times customers are not always supplied a list of Service codes found in their tariff. Using this function with the correct customer TariffHeaderID value would provide this list of Service levels or codes that are available as well as rate all of them all at once in a single response. |
Error Codes
Error responses are formatted similarly to the responses found in the Retrieving Data section. The only change is the IsError flag — it should be set to true — with an Error Message populating the Message value in the response. There is always a full dsQuote object whether this call results in a success or failure response. In the case of a success, this object populates with the corresponding Rating information. The RateAllServices and Rate error codes are described here:
| Function | Description |
|---|---|
| RateAllServices |
|
| Rate |
|
Endpoints
SOAP
https://ws.pilotair.com/tms2.1/tms/PilotServiceRequest.asmx
SOAP (Dev/Test)
https://ws.pilotair.com/tms2.1/tms/PilotServiceRequest.asmx
WSDL
https://ws.pilotair.com/tms2.1/tms/PilotServiceRequest.asmx?WSDL
WSDL (Dev/Test))
https://ws.pilotair.com/tms2.1/tms/PilotServiceRequest.asmx?WSDL
REST
https://wsi.pilotdelivers.com/pilotapi/v1/Ratings
REST Developer Playground
https://wsi.pilotdelivers.com/pilotapi/swagger/ui/index
REST (Dev/Test)
https://wsi.pilotdelivers.com/pilotapi/test/v1/Ratings
REST Developer Playground (Dev/Test)
https://wsi.pilotdelivers.com/pilotapi/test/swagger/ui/index
Security/Authentication
Although this API does not use traditional or industry-standardized authentication mechanisms, Maersk uses a level of abstraction to ensure the caller is indeed using valid ID values in the form of LocationID and TariffHeaderID values. Mainly, LocationID is related and established as part of a key pair when a customer location is added to a customer’s CoPilot account. TariffHeaderID comes directly from and identifies the customer’s tariff to use in the Rating of the given shipment information. TariffHeaderID cannot be set to 0.
Resources
Retrieving Data
- GetNewQuote (SOAP)
- GetQuote (SOAP)
- GetQuote (REST)
- Rate (SOAP)
- Rate (REST)
- RateAllServices (SOAP)
- RateAllServices (REST)
SOAP Response Example
The following response object example for the functions RateAllServices, Rate, and GetQuote is called dsQuote. To get the request object to populate, the function GetNewQuote should be called.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<RateAllServicesResponse xmlns="http://www.pilotair.com/">
<RateAllServicesResult>
<IsError>false</IsError>
<dsQuote>
<xs:schema id="dsTQSQuote" targetNamespace="http://tempuri.org/dsTQSQuote.xsd" xmlns:mstns="http://tempuri.org/dsTQSQuote.xsd" xmlns="http://tempuri.org/dsTQSQuote.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" attributeFormDefault="qualified" elementFormDefault="qualified">
<xs:element name="dsTQSQuote" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="TQSQuote">
<xs:complexType>
<xs:sequence>
<xs:element name="QuoteID" type="xs:int" minOccurs="0" />
<xs:element name="TariffID" type="xs:int" minOccurs="0" />
<xs:element name="Scale" type="xs:string" minOccurs="0" />
<xs:element name="LocationID" type="xs:int" />
<xs:element name="TransportByAir" type="xs:boolean" minOccurs="0" />
<xs:element name="CalculateBillCode" type="xs:boolean" minOccurs="0" />
<xs:element name="IsSaveQuote" type="xs:boolean" default="true" minOccurs="0" />
<xs:element name="IATA_Classifications" type="xs:int" minOccurs="0" />
<xs:element name="PackingContainers" type="xs:int" minOccurs="0" />
<xs:element name="DeclaredValue" type="xs:double" minOccurs="0" />
<xs:element name="InsuranceValue" type="xs:double" minOccurs="0" />
<xs:element name="COD" type="xs:double" minOccurs="0" />
<xs:element name="TariffName" type="xs:string" />
<xs:element name="Notes" type="xs:string" minOccurs="0" />
<xs:element name="Service" type="xs:string" minOccurs="0" />
<xs:element name="QuoteDate" type="xs:dateTime" minOccurs="0" />
<xs:element name="ChargeWeight" type="xs:int" minOccurs="0" />
<xs:element name="TotalPieces" type="xs:int" minOccurs="0" />
<xs:element name="ShipDate" type="xs:dateTime" minOccurs="0" />
<xs:element name="TariffHeaderID" type="xs:int" minOccurs="0" />
<xs:element name="UserID" type="xs:int" minOccurs="0" />
<xs:element name="QuoteConfirmationEmail" type="xs:string" minOccurs="0" />
<xs:element name="DebrisRemoval" type="xs:boolean" minOccurs="0" />
<xs:element name="Gateway" type="xs:string" default="" minOccurs="0" />
<xs:element name="IsInternational" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="Shipper" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string" minOccurs="0" />
<xs:element name="PDArea" type="xs:string" minOccurs="0" />
<xs:element name="Address1" type="xs:string" minOccurs="0" />
<xs:element name="Address2" type="xs:string" minOccurs="0" />
<xs:element name="City" type="xs:string" minOccurs="0" />
<xs:element name="State" type="xs:string" minOccurs="0" />
<xs:element name="Zipcode" type="xs:string" minOccurs="0" />
<xs:element name="Airport" type="xs:string" minOccurs="0" />
<xs:element name="Attempted" type="xs:boolean" minOccurs="0" />
<xs:element name="PrivateRes" type="xs:boolean" minOccurs="0" />
<xs:element name="Hotel" type="xs:boolean" minOccurs="0" />
<xs:element name="Inside" type="xs:boolean" minOccurs="0" />
<xs:element name="Liftgate" type="xs:boolean" minOccurs="0" />
<xs:element name="TwoManHours" type="xs:double" minOccurs="0" />
<xs:element name="WaitTimeHours" type="xs:double" minOccurs="0" />
<xs:element name="Special" type="xs:string" minOccurs="0" />
<xs:element name="DedicatedVehicle" type="xs:string" minOccurs="0" />
<xs:element name="Miles" type="xs:int" minOccurs="0" />
<xs:element name="Canadian" type="xs:boolean" minOccurs="0" />
<xs:element name="ServiceCode" type="xs:string" minOccurs="0" />
<xs:element name="Convention" type="xs:boolean" minOccurs="0" />
<xs:element name="Country" type="xs:string" minOccurs="0" />
<xs:element name="IsBeyond" type="xs:boolean" minOccurs="0" />
<xs:element name="BeyondServiceArea" type="xs:string" minOccurs="0" />
<xs:element name="Station" type="xs:string" minOccurs="0" />
<xs:element name="AirtrakNo" type="xs:int" default="0" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Consignee" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Name" type="xs:string" minOccurs="0" />
<xs:element name="PDArea" type="xs:string" minOccurs="0" />
<xs:element name="Address1" type="xs:string" minOccurs="0" />
<xs:element name="Address2" type="xs:string" minOccurs="0" />
<xs:element name="City" type="xs:string" minOccurs="0" />
<xs:element name="State" type="xs:string" minOccurs="0" />
<xs:element name="Zipcode" type="xs:string" minOccurs="0" />
<xs:element name="Airport" type="xs:string" minOccurs="0" />
<xs:element name="Attempted" type="xs:boolean" minOccurs="0" />
<xs:element name="PrivateRes" type="xs:boolean" minOccurs="0" />
<xs:element name="Hotel" type="xs:boolean" minOccurs="0" />
<xs:element name="Inside" type="xs:boolean" minOccurs="0" />
<xs:element name="Liftgate" type="xs:boolean" minOccurs="0" />
<xs:element name="TwoManHours" type="xs:double" minOccurs="0" />
<xs:element name="WaitTimeHours" type="xs:double" minOccurs="0" />
<xs:element name="Special" type="xs:string" minOccurs="0" />
<xs:element name="DedicatedVehicle" type="xs:string" minOccurs="0" />
<xs:element name="Miles" type="xs:int" minOccurs="0" />
<xs:element name="Canadian" type="xs:boolean" minOccurs="0" />
<xs:element name="ServiceCode" type="xs:string" minOccurs="0" />
<xs:element name="Convention" type="xs:boolean" minOccurs="0" />
<xs:element name="Country" type="xs:string" minOccurs="0" />
<xs:element name="IsBeyond" type="xs:boolean" minOccurs="0" />
<xs:element name="BeyondServiceArea" type="xs:string" minOccurs="0" />
<xs:element name="Station" type="xs:string" minOccurs="0" />
<xs:element name="AirtrakNo" type="xs:int" default="0" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="LineItems" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="LineRow" type="xs:int" minOccurs="0" />
<xs:element name="Pieces" type="xs:int" minOccurs="0" />
<xs:element name="Weight" type="xs:int" minOccurs="0" />
<xs:element name="Description" type="xs:string" minOccurs="0" />
<xs:element name="Length" type="xs:int" minOccurs="0" />
<xs:element name="Width" type="xs:int" minOccurs="0" />
<xs:element name="Height" type="xs:int" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Quote" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="Service" type="xs:string" />
<xs:element name="DimWeight" type="xs:int" minOccurs="0" />
<xs:element name="TotalQuote" type="xs:double" minOccurs="0" />
<xs:element name="Oversized" type="xs:boolean" minOccurs="0" />
<xs:element name="OversizedServiceArea" type="xs:string" minOccurs="0" />
<xs:element name="AbleToCalculate" type="xs:boolean" minOccurs="0" />
<xs:element name="ChargeWeight" type="xs:int" minOccurs="0" />
<xs:element name="Beyond" type="xs:boolean" minOccurs="0" />
<xs:element name="DisplayService" type="xs:string" minOccurs="0" />
<xs:element name="TopLine" type="xs:double" minOccurs="0" />
<xs:element name="UpgradeRequiredForServiceArea" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="LinkForShipping" type="xs:string" minOccurs="0" />
<xs:element name="DeliveryDate" type="xs:dateTime" minOccurs="0" />
<xs:element name="ExtendedTopLine" type="xs:double" minOccurs="0" />
<xs:element name="Breakdown" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="ChargeCode" type="xs:int" minOccurs="0" />
<xs:element name="Charge" type="xs:double" minOccurs="0" />
<xs:element name="BillCodeName" type="xs:string" />
<xs:element name="Steps" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
<dsTQSQuote xmlns="http://tempuri.org/dsTQSQuote.xsd">
<TQSQuote diffgr:id="TQSQuote1" msdata:rowOrder="0" diffgr:hasChanges="modified" msdata:hiddenTQSQuote_Id="0">
<QuoteID></QuoteID>
<TariffID></TariffID>
<Scale></Scale>
<LocationID></LocationID>
<TransportByAir></TransportByAir>
<CalculateBillCode></CalculateBillCode>
<IsSaveQuote></IsSaveQuote>
<IATA_Classifications></IATA_Classifications>
<PackingContainers></PackingContainers>
<DeclaredValue></DeclaredValue>
<InsuranceValue></InsuranceValue>
<COD></COD>
<TariffName />
<Notes />
<Service />
<QuoteDate></QuoteDate>
<ChargeWeight></ChargeWeight>
<TotalPieces></TotalPieces>
<ShipDate></ShipDate>
<TariffHeaderID></TariffHeaderID>
<UserID></UserID>
<QuoteConfirmationEmail />
<DebrisRemoval></DebrisRemoval>
<Gateway></Gateway>
<IsInternational></IsInternational>
<Shipper diffgr:id="Shipper1" msdata:rowOrder="0" msdata:hiddenTQSQuote_Id="0">
<Name />
<PDArea></PDArea>
<Address1 />
<Address2 />
<City />
<State></State>
<Zipcode></Zipcode>
<Airport></Airport>
<Attempted></Attempted>
<PrivateRes></PrivateRes>
<Hotel></Hotel>
<Inside></Inside>
<Liftgate></Liftgate>
<TwoManHours></TwoManHours>
<WaitTimeHours></WaitTimeHours>
<Special></Special>
<DedicatedVehicle></DedicatedVehicle>
<Miles></Miles>
<Canadian></Canadian>
<ServiceCode></ServiceCode>
<Convention></Convention>
<Country></Country>
<IsBeyond></IsBeyond>
<BeyondServiceArea />
<Station></Station>
<AirtrakNo></AirtrakNo>
</Shipper>
<Consignee diffgr:id="Consignee1" msdata:rowOrder="0" msdata:hiddenTQSQuote_Id="0">
<Name />
<PDArea></PDArea>
<Address1 />
<Address2 />
<City />
<State></State>
<Zipcode></Zipcode>
<Airport></Airport>
<Attempted></Attempted>
<PrivateRes></PrivateRes>
<Hotel></Hotel>
<Inside></Inside>
<Liftgate></Liftgate>
<TwoManHours></TwoManHours>
<WaitTimeHours></WaitTimeHours>
<Special></Special>
<DedicatedVehicle></DedicatedVehicle>
<Miles></Miles>
<Canadian></Canadian>
<ServiceCode></ServiceCode>
<Convention></Convention>
<Country></Country>
<IsBeyond></IsBeyond>
<BeyondServiceArea />
<Station></Station>
<AirtrakNo></AirtrakNo>
</Consignee>
<LineItems diffgr:id="LineItems1" msdata:rowOrder="0" msdata:hiddenTQSQuote_Id="0">
<LineRow></LineRow>
<Pieces></Pieces>
<Weight></Weight>
<Description></Description>
<Length></Length>
<Width></Width>
<Height></Height>
</LineItems>
<Quote diffgr:id="Quote1" msdata:rowOrder="0" msdata:hiddenQuote_Id="0" msdata:hiddenTQSQuote_Id="0">
<Service></Service>
<DimWeight></DimWeight>
<TotalQuote></TotalQuote>
<Oversized></Oversized>
<OversizedServiceArea>""</OversizedServiceArea>
<AbleToCalculate></AbleToCalculate>
<ChargeWeight></ChargeWeight>
<Beyond></Beyond>
<DisplayService></DisplayService>
<TopLine></TopLine>
<UpgradeRequiredForServiceArea></UpgradeRequiredForServiceArea>
<LinkForShipping></LinkForShipping>
<ExtendedTopLine></ExtendedTopLine>
<Breakdown diffgr:id="Breakdown1" msdata:rowOrder="0" msdata:hiddenQuote_Id="0">
<ChargeCode></ChargeCode>
<Charge></Charge>
<BillCodeName></BillCodeName>
<Steps></Steps>
</Breakdown>
<Breakdown diffgr:id="Breakdown2" msdata:rowOrder="1" msdata:hiddenQuote_Id="0">
<ChargeCode></ChargeCode>
<Charge></Charge>
<BillCodeName></BillCodeName>
<Steps></Steps>
</Breakdown>
</Quote>
</TQSQuote>
</dsTQSQuote>
<diffgr:before>
<TQSQuote diffgr:id="TQSQuote1" msdata:rowOrder="0" msdata:hiddenTQSQuote_Id="0" xmlns="http://tempuri.org/dsTQSQuote.xsd">
<QuoteID></QuoteID>
<TariffID></TariffID>
<Scale></Scale>
<LocationID></LocationID>
<TransportByAir></TransportByAir>
<CalculateBillCode></CalculateBillCode>
<IsSaveQuote></IsSaveQuote>
<IATA_Classifications></IATA_Classifications>
<PackingContainers></PackingContainers>
<DeclaredValue></DeclaredValue>
<InsuranceValue></InsuranceValue>
<COD>0</COD>
<TariffName />
<Notes />
<Service />
<QuoteDate></QuoteDate>
<ChargeWeight></ChargeWeight>
<TotalPieces></TotalPieces>
<ShipDate></ShipDate>
<TariffHeaderID></TariffHeaderID>
<UserID></UserID>
<QuoteConfirmationEmail />
<DebrisRemoval></DebrisRemoval>
<Gateway></Gateway>
<IsInternational></IsInternational>
</TQSQuote>
</diffgr:before>
</diffgr:diffgram>
</dsQuote>
</RateAllServicesResult>
</RateAllServicesResponse>
</soap:Body>
</soap:Envelope>