Transcription
Your Guide to EmbeddingAramex’s Tracking APIYour Guide to EmbeddingAramex’s Tracking API
Your Guide to EmbeddingAramex’s Tracking APITable of ContentsVersion History . 3Getting Started: Shipping API . 4Security Certificate: . 4Tracking API . 5Introduction . 5Features: . 5Security: . 5Encryption: . 5Simple and easy to use: . 5Flexibility: . 5Main Functionalities: . 5Tracking API . 5Using Shipment Tracking API: How does it Work? . 6Xml Structure Diagrams: . 7Tracking Service . 712Methods: . 81.1Shipment tracking method: . 81.2Request Elements . 91.3Response Elements. 11Data Type Element Description. 132.1Client Info . 13Testing credentials . 142.2Transaction . 14Aramex International Shipping Information 1
Your Guide to EmbeddingAramex’s Tracking APIList of TablesTable 1: Tracking service . 7Table 2: Shipment Tracking Request & Response . 8Table 3: Shipment Tracking Request Elements . 9Table 4: Shipment Tracking Response Elements . 11Table 5: List of Elements present in the Client Structure . 13Table 6: List of Elements present in the Transaction Structure . 14List of FiguresFig.1. Tracking WSDL Service . 7Fig.2. Shipment Tracking Structure Request . 8Fig.3. Shipment Tracking Structure Response . 8Fig.4. Client Info Structure Diagram . 9Fig.5. Transaction Structure Diagram . 10Fig.6. Shipments Structure Diagram . 10Fig.7. Get Last Tracking Update Only Structure Diagram . 10Fig.8. Notification Structure Diagram. 11Fig.9. Transaction Structure Diagram . 11Fig.10. Has Errors Structure Diagram . 11Fig.11. Tracking Result Structure Diagram . 12Aramex International Shipping Information 2
Your Guide to EmbeddingAramex’s Tracking APIVersion HistoryVersion12ChangeDocument CreationNew Sections- Add the securitycertificate (page 4)- Add testing credentials(page 14)Effective DateJune 20111st of January 2013Aramex International Shipping Information 3
Your Guide to EmbeddingAramex’s Tracking APIGetting Started: Shipping APIThe Aramex Shipping API (Application Programming Interface) allows your system to communicatedirectly with our shipping and tracking systems over the internet. Aramex Shipping API provides youwith a wide range of functionalities which enables your systems and applications to integrate directlywith Aramex’s systems in an easy and automated way. The APIs are built based on SOAP (SimpleObject Access Protocol) providing a secure channel of communication, as all web calls are madethrough secured HTTPS.A SOAP message is an ordinary XML document containing the following elements: An Envelope element that identifies the XML document as a SOAP message (required)A Header element containing header information (optional)A Body element containing call and response information (required)A Fault element containing errors and status information (optional)Security Certificate:To connect securely through HTTPs to our testing website the certificate in the following link will need to bedownloaded, a manual is also present through the below link to guide the user through the download andinstallation of the is certificate should be imported and trusted on the machine or user account used to connect to our testingwebsite.Testing service 1 0.svcLive ice 1 0.svcAramex International Shipping Information 4
Your Guide to EmbeddingAramex’s Tracking APITracking APIIntroductionThis document contains a complete guide on how to use the Tracking API, which could be a helpfulafter-service tool that we offer to complete the Shipment creation service in the Shipping ServicesAPI. The Tracking API is part of Aramex Shipping APIs, which allows you to track existing shipmentsand obtain their updates and latest status.Features:The Tracking API provides these features:Security:Two levels of security are provided for each method:a) Each submitted request should contain a valid email address and password which are obtainedby registering your email address on aramex.com. This is used for authorizing the request.b) Each submitted request should contain a valid account number and a valid PIN code. This isused to authenticate and verify the identity of the customer.Encryption:By using HTTPS all transmissions are insured to be encrypted.Simple and easy to use:Shipment Updates are easily obtained by simply adding the AWB (Airway bill) numbers to beretrieved.Flexibility:Users can choose to only obtain the latest update for any shipment.Main Functionalities:Tracking APIAllows users to track the status and obtain updates of existing shipments.- The Ability to add several AWB (Airway bill) numbers to the list and to retrieve their data.Aramex International Shipping Information 5
Your Guide to EmbeddingAramex’s Tracking APIUsing Shipment Tracking API: How does it Work? The Tracking API uses a Web Service Definition Language (WSDL) that can be downloaded 82/Tracking-API, enabling developers to addreference to the web service in their code. The user must be registered at http://www.aramex.com with a valid user name and password. Sample Codes are available in VB.NET, C# and PHP, downloadable 82/Tracking-API.Users are free to use any development tool provided these tools support the WSDL and messagesconform to the standards and structure required. However the preferred programming languages forclient implementations are: Visual Basic 2005 (with VB.NET framework 2) or laterC#PHPAramex International Shipping Information 6
Your Guide to EmbeddingAramex’s Tracking APIXml Structure Diagrams:XML requests or reply messages have to be constructed. The Tables below show the structure, element, childelement, semantics as well as the validation conditions in the Tracking API XML.Tracking ServiceTable 1: Tracking serviceDiagramDescriptionThis WSDL Serviceincludes theShipment trackingservice method.Shipment Trackingmethod involves anInput (request) andOutput (response),along with theirdesignedparameters.Fig.1. Tracking WSDL ServiceAramex International Shipping Information 7
Your Guide to EmbeddingAramex’s Tracking API1 Methods:This is a general outlook on the method diagrams, their overall description and requirements.1.1Shipment tracking method:Table 2: Shipment Tracking Request & This methodallows the user totrack an existingshipment’supdates and lateststatus.The requirednodes to be filledare: ClientInfo andShipments.Fig.2. Shipment Tracking Structure RequestShipmentTrackingResponse:Obtains trackingupdates forspecified AWBs.The TransactionParameter is sentas filled in therequest foridentificationpurposes.Fig.3. Shipment Tracking Structure ResponseAramex International Shipping Information 8
Your Guide to EmbeddingAramex’s Tracking API1.2Request ElementsThese elements present the request structure of the Tracking API (Shipment Tracking).Table 3: Shipment Tracking Request ElementsDiagramDescriptionClient Info:All the child elements are mandatory andneed to be filled.The user name and password arevalidated to allow access to the service.Version element, is the Version of the APIthe customer is using, which needs to bespecified in the request.Account Number, Pin, Entity and CountryCode are all needed to verify the user’saccount.For a more detailed description of theelements refer to Table 5.Fig.4. Client Info Structure DiagramAramex International Shipping Information 9
Your Guide to EmbeddingAramex’s Tracking APITransaction:Please note that the Transaction element isnot validated, and is also present in themethod requests and returned in theresponses for identification purposes.Any type of data can be included by theuser.For a more detailed description of theelements, refer to Table 6.Fig.5. Transaction Structure DiagramShipments:Fig.6. Shipments Structure DiagramThe Shipments element accepts severalAWB numbers to be added to the list fortheir data retrieval.Get Last Tracking Update Only:Fig.7. Get Last Tracking Update Only Structure DiagramA Boolean value which determines whetherthe user requires all the updates associatedwith the shipment or only the latest one.Aramex International Shipping Information 10
Your Guide to EmbeddingAramex’s Tracking API1.3Response ElementsThe Response has four elements (notification, transaction, has errors, tracking results)Table 4: Shipment Tracking Response ElementsDiagramDescriptionNotification:Contains detailsdescribing the errors orsuccess.Fig.8. Notification Structure DiagramCode To Identify thenotification category.Message Deeperdescription of theNotification.Transaction:Contains the data sent inthe request by the user,used mainly foridentification purposes.Fig.9. Transaction Structure DiagramHasErrors:Fig.10. Has Errors Structure DiagramReturns True if thereare errors and False ifthere aren’t.Aramex International Shipping Information 11
Your Guide to EmbeddingAramex’s Tracking APITracking Result:Returns the shipment’supdates in the form ofunique records, withthe tracking resultelements as fields.Fig.11. Tracking Result Structure DiagramAramex International Shipping Information 12
Your Guide to EmbeddingAramex’s Tracking API2 Data Type Element DescriptionFurther details on complex child elements of the Tracking API and their attributes are shown below.Element: Element NameData Type: The type of data that can be inserted into this field.Required: Specifies three categories M Mandatory, This field must be filled in all cases.O Optional, This field may or may not be filled.C Conditional, This field may or may not be filled depending on another field being filled.Length: The maximum number of characters allowed in this field.Allowed Values: Specifies the accepted data of each field.2.1Client InfoTable 5: List of Elements present in the Client StructureElementUser NameDataTypeStringRequired Length AllowedValuesM50DescriptionPasswordStringM50A unique password to verify the user name,sent to the user upon registration ityAccountNumberAccount ingM2Based on the WSDL version the user is using toinvoke the web serviceIdentification Code for Transmitting Party. Thiscode should be provided to you by Aramex.The Customer’s Account number provided byAramex when the contract is signed.A key that is associated with the accountnumber, so as to validate customer identity.Two Letter Code Identifying the Country.Refer to Appendix DA unique user name sent to the user uponregistration with http://www.aramex.comAramex International Shipping Information 13
Your Guide to EmbeddingAramex’s Tracking API2.1.1 Testing credentialsTo be able to test the Tracking API on our testing website, the user credentials below can be used:AccountCountryCode JOAccountEntity AMMAccountNumber 20016AccountPin 331421UserName testingapi@aramex.comPassword R123456789 rVersion v1.02.2TransactionTable 6: List of Elements present in the Transaction StructureElementDataTypeRequiredLengthReference 1StringO50Reference 2StringO50Reference 3StringO50Reference 4StringO50Reference 5StringO50AllowedValuesDescriptionAny details the user would like to add that willbe sent back in the response.Any details the user would like to add that willbe sent back in the response.Any details the user would like to add that willbe sent back in the response.Any details the user would like to add that willbe sent back in the response.Any details the user would like to add that willbe sent back in the response.Aramex International Shipping Information 14
The Aramex Shipping API (Application Programming Interface) allows your system to communicate directly with our shipping and tracking systems over the internet. Aramex Shipping API provides you with a wide range of functionalities which enables your systems and applications to integrate directly with Aramex’s systems in an easy and automated way.
