Transcription
Aramex’s Guide to Embeddingthe Shipping Services API
Your guide to embedding Aramex’sShipping APITable of ContentsGetting Started: Shipping API . 8Security Certificate . 8Testing URL . 8Live URL . 8Shipping API. 9Introduction . 9Features. 9Security . 9Encryption . 9Simple and easy to use . 9Flexibility . 9Accuracy and error handling . 10Main Functionalities . 11Creating shipments . 11Printing labels . 11Creating pickups . 11Cancelling pickups . 11ScheduleDelivery . 11ReserveShipmentNumberRange. 11GetLastShipmentsNumbersRange . 11Using Shipping Services API: How does it Work? . 12Xml Structure Diagrams: . 12Shipping API. 131Methods . 141.1Shipment Creation method: . 141.2Label Printing Method . 15Aramex International Shipping Information1
Your guide to embedding Aramex’sShipping API21.3Pickup Creation Method . 161.4Pickup Cancellation Method . 171.5Reserve Shipment Number Range Method . 181.6Get Last Shipments Numbers Range Method . 191.7Schedule Delivery Method . 20Elements Data structure . 222.1General Request Elements . 222.2General Response Elements . 242.3Shipment Creation Elements . 252.4Pickup Creation Elements . 273Complex Data Type Structure . 304Data Type Element Description. 354.1Client Info . 354.1.1 Testing credentials . 364.2Transaction . 364.3Shipment . 374.4Party. 394.5Address. 394.6Contact . 404.7Shipment Details. 414.8Date Time . 434.9Shipment Items . 434.10Attachment . 434.11Label Info . 444.12Dimensions . 444.13Weight . 454.14Money . 454.15Volume . 454.16Pickup Details . 464.17Pickup Item. 47Aramex International Shipping Information2
Your guide to embedding Aramex’sShipping API4.18Reserve Shipment Number Range . 484.19Get Last Shipments Numbers Range . 484.20Schedule Delivery . 49APPENDIX: Aramex and General References . 50Appendix A – Product Types . 50Appendix B – Shipment Payment Methods . 51Appendix C – Service Codes . 51Appendix D – ISO Country Codes . 52Appendix E – Currency Codes . 55Appendix F – Error Codes and Messages . 61Aramex International Shipping Information3
Your guide to embedding Aramex’sShipping APIList of TablesTable 1: The Shipping API structural diagram . 13Table 2: Shipment Creation Request & Response . 14Table 3: Label Printing Request & Response . 15Table 4: Pickup Creation Request & Response . 16Table 5: Pickup Cancelation Request & Response . 17Table 6: Reserve Shipment Number Range Request & Response. 18Table 7: Get Last Shipments Numbers Range Request & Response . 19Table 8: Schedule Delivery Request & Response . 20Table 9: General Request Elements - Client Info & Transaction . 22Table 10: General Response Elements . 24Table 11: Shipment Creation Request Elements . 25Table 12: Shipment Creation Response Element . 26Table 13: Pickup Creation Request Elements . 27Table 14: Pickup Creation Response Element . 29Table 15: Data Type Structure . 30Table 16: List of Elements present in the Client Structure . 35Table 17: List of Elements present in the Transaction Structure . 36Table 18: List of Elements present in the Shipment Structure . 37Table 19: List of Elements present in the Party Structure . 39Table 20: List of Elements present in the Address Structure . 39Table 21: List of Elements present in the Contact Structure . 40Table 22: list of Elements present in the Shipment Details Structure . 41Table 23: list of Elements present in the Date Time Structure . 43Table 24: list of Elements present in the Shipment Item Structure . 43Table 25: list of Elements present in the Attachment Structure . 43Table 26: list of Elements present in the Label Info Structure . 44Table 27: list of Elements present in the Dimensions Structure . 44Table 28: list of Elements present in the Weight Structure . 45Aramex International Shipping Information4
Your guide to embedding Aramex’sShipping APITable 29: list of Elements present in the Money Structure . 45Table 30: list of Elements present in the Volume Structure . 45Table 31: list of Elements present in the Pickup Details Structure . 46Table 32: list of Elements present in the Pickup Item Structure . 47Aramex International Shipping Information5
Your guide to embedding Aramex’sShipping APIList of FiguresFig.1. Shipping WSDL Service. 13Fig.2. Shipment Creation Structure Request . 14Fig.3. Shipment Creation Structure Response . 14Fig.4. Label Printing Structure Request . 15Fig.5. Label Printing Structure Response . 15Fig.6. Pickup Creation Structure Request . 16Fig.7. Pickup Creation Structure Response. 16Fig.8. Pickup Cancelation Structure Request . 17Fig.9. Pickup Cancelation Structure Response. 17Fig.10. Reserve Range Structure Request . 18Fig.11. Reserve Range Structure Response . 18Fig.12. Last Reserved Shipment Number Structure Request. 19Fig.13. Last Reserved Shipment Number Structure Response . 19Fig.14. Scheduled Delivery Structure Request . 20Fig.15. Scheduled Delivery Structure Response . 21Fig.16. Client Info Structure Diagram . 22Fig.17. Transaction Structure Diagram . 23Fig.18. Notification Structure Diagram . 24Fig.19. Transaction Structure Diagram . 24Fig.20. Has Errors Structure Diagram . 24Fig.22. Label Info Structure Diagram . 26Fig.23. Processed Shipment Structure Diagram . 26Fig.24. Pickup Structure Diagram . 27Fig.25. Pickup Item Details Structure Diagram . 28Fig.26. Shipment Structure Diagram . 29Fig.27. Address Structure Diagram . 30Fig.28. Shipment Item Structure Diagram . 30Fig.29. Contact Structure Diagram . 31Aramex International Shipping Information6
Your guide to embedding Aramex’sShipping APIFig.30. Party Structure Diagram . 32Fig.31. Money Structure Diagram . 32Fig.32. Weight Structure Diagram . 32Fig.33. Attachment Structure Diagram . 33Fig.34. Dimensions Structure Diagram . 33Fig.35. Volume Structure Diagram . 33Fig.36. Shipment Label Structure Diagram . 34Aramex International Shipping Information7
Your guide to embedding Aramex’sShipping APIGetting Started: Shipping APIThe Aramex Shipping API (Application Programing 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 system and applications to integrate directlywith Aramex’s systems in an easy and automated way. The APIs are built based on SOAP (SimpleObject Access Protocol) and provide 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 CertificateTo 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 URLsPlease refer to APPENDIX GLive URLsPlease refer to APPENDIX HAramex International Shipping Information8
Your guide to embedding Aramex’sShipping APIShipping APIIntroductionThis document contains a complete guide on how to use the Shipping Services API, which is one of themain functionalities required by customers to start shipping. The Shipping API Service is part of theavailable APIs at Aramex allowing you to create shipments, generate labels, create and cancel pick uprequests, control and retrieve your shipment number ranges as well as schedule a pinpoint delivery ofyour shipment.FeaturesThe Shipping Services API provides these features:SecurityTwo 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.EncryptionBy using HTTPS all transmission are insured to be encrypted.Simple and easy to useCreating shipments, requesting pickups and other functionalities are easily generated by providingvery basic and simple information about the shipper, consignee and shipmentsFlexibility Users can have different means of providing the same information.Pickup request can be generated with detailed shipments information, or just a summaryabout the shipments. Shipments can be added to a pickup request after the request has beencreated.A printing label can be requested within the shipment creation request or as a separate labelprinting request by simply providing the Airway bill number to print.Aramex International Shipping Information9
Your guide to embedding Aramex’sShipping APIAccuracy and error handlingDuring the process of shipment or pickup creation, the submitted information such as addresses,payment methods and more, goes through a detailed validation procedure to insure the validity andcorrectness. In case of errors, detailed descriptive error messages are provided in the generatedresponse.Aramex International Shipping Information10
Your guide to embedding Aramex’sShipping APIMain FunctionalitiesCreating shipmentsAllows you to create shipments, providing a wide range of options for customers to provide full detailsabout their shipments, such as:1. Attaching additional documentation:a) Clients can attach Performa Invoices, clearance forms or any other documentation required.2. Generating a label for the Shipment being created.3. Providing us with sensitive details such as Operations (Handling) instructions.4. Adding Shipments to an existing pickup, given that the pickup is un-assigned or pending details.Printing labelsAllows you to generate shipping labels for an existing shipment. Users will be provided with the reportID used to generate the label. Also, different label formats are available for customers to use and thecustomer can specify which format by providing the report ID in the request.Two methods are provided for getting and printing the label from the customer side, a URL todownload the PDF file, or a data stream that will be provided in the response message.Creating pickupsAllows you to create pickups, providing flexible options such as:- After a pickup is created, shipments can be added later to it through the Create Shipmentsfunction, given that the pickup is un-assigned or pending details.Cancelling pickupsAllows you to cancel an existing pickup, assuming it has not been assigned to a courier or processedby the dispatcher.ScheduleDeliveryAllows you to schedule a shipment delivery at a specified date and time to a pinpointed longitude andlatitude.ReserveShipmentNumberRangeAllows you to reserve a numerical range for your shipment identification numbers.GetLastShipmentsNumbersRangeAllows you to inquire about the stock range for an entity and product group combination.Aramex International Shipping Information11
Your guide to embedding Aramex’sShipping APIUsing Shipping Services API: How does it Work? The user must be registered at http://www.aramex.com with a valid user name and password. Sample Codes are available in VB.NET and JSON, downloadable 94/Shipping-Services-API. Users are free to use any development tool provided these tools support the standards andstructure required.Xml Structure Diagrams:XML request or reply messages have to be constructed as follows. The Tables below show the structure,element, child element, semantics as well as the validation conditions in the Shipping API message.Aramex International Shipping Information12
Your guide to embedding Aramex’sShipping APIShipping APITable 1: The Shipping API structural diagramDiagramDescriptionThis Serviceincludesseveralmethods asshown in Fig.1.Each methodhas an Input(Request) andOutput(Response),with theirdesignedparameters.Fig.1. Shipping WSDL ServiceAramex International Shipping Information13
Your guide to embedding Aramex’sShipping API1 MethodsA General outlook on the method diagrams, their overall description and requirements.1.1Shipment Creation method:Table 2: Shipment Creation Request & ResponseDiagramDescriptionShipment CreationRequest:This method allowsusers to createshipments onAramex’s system.The required nodesto be filled are: ClientInfo and Shipments,Their elements andfurther descriptioncan be found inTables 9 and 11Shipment CreationResponse:Fig.2. Shipment Creation Structure RequestFig.3. Shipment Creation Structure ResponseInforms the user onthe status of theirsubmitted shipment.Success an AWBnumber is suppliedFailure an errormessage specificallystates the location ofthe error and itsnature. TheTransactionParameter is sent asfilled in the requestfor identificationpurposes. Theirelements and furtherdescription can befound in Tables 10and 12Aramex International Shipping Information14
Your guide to embedding Aramex’sShipping API1.2Label Printing MethodTable 3: Label Printing Request & ResponseDiagramDescriptionLabel PrintingRequest:This method allows theuser to print a label foran existing shipment.The required nodes tobe filled are ClientInfoand ShipmentNumber. Ifthere is a duplicateShipment Number thenthe ProductGroup andOriginEntity elementsare required. Theirelements and furtherdescription can be foundin. Fig. 22 – Tables 9and 11.Fig.4. Label Printing Structure RequestLabel PrintingResponse:Returns the created label,if all the requiredinformation in therequest is inserted andvalidated correctly.The Transaction andShipment Numberparameters are returnedfrom the request foridentification purposes.Their elements andfurther description canbe found in Fig.36 –Tables 10 and 12.Fig.5. Label Printing Structure ResponseAramex International Shipping Information15
Your guide to embedding Aramex’sShipping API1.3Pickup Creation MethodTable 4: Pickup Creation Request & ResponseDiagramDescriptionPickup CreationRequest:This method allowsusers to create apickup request.The nodes requiredto be filled are asfollows: ClientInfoand Pickup. Theirelements andfurther descriptioncan be found inFig.22. – Tables 6, 8and 10.Fig.6. Pickup Creation Structure RequestPickup CreationResponse:Informs the user onthe status of theirsubmitted pickuprequest.Fig.7. Pickup Creation Structure ResponseSuccess aCollection (Pickup)reference is suppliedFailure an errormessage specificallystates the location ofthe error and itsnature.The TransactionParameter is sent asfilled in the requestfor identificationpurposes. Theirelements andfurther descriptioncan be found inTables 7 and 11Aramex International Shipping Information16
Your guide to embedding Aramex’sShipping API1.4Pickup Cancellation MethodTable 5: Pickup Cancelation Request & :This methodallows you tocancel a pickupas long as it isun-assigned orpending details.Their elementsand furtherdescription canbe found inTable 6.Fig.8. Pickup Cancelation Structure RequestPickupCancelationResponse:Fig.9. Pickup Cancelation Structure ResponseInforms the userthat the pickupwas successfullycanceled.Their elementsand furtherdescription canbe found inTable 7.Aramex International Shipping Information17
Your guide to embedding Aramex’sShipping API1.5Reserve Shipment Number Range MethodTable 6: Reserve Shipment Number Range Request & ResponseDiagramDescriptionReserve RangeRequest:This method allowsyou to reserve a rangeof shipment numbers.Their elements andfurther description canbe found in Tables 9and 33.Fig.10. Reserve Range Structure RequestReserve RangeResponse:Returns the assignedWaybill range to beused.Their elements andfurther description canbe found in Table 10.Fig.11. Reserve Range Structure ResponseAramex International Shipping Information18
Your guide to embedding Aramex’sShipping API1.6Get Last Shipments Numbers Range MethodTable 7: Get Last Shipments Numbers Range Request & ResponseDiagramDescriptionLast ReservedShipmentNumberRequest:This methodallows you toinquire aboutthe last reservedrange using aspecific entityand productgroupFig.12. Last Reserved Shipment Number Structure RequestTheir elementsand furtherdescription canbe found inTables 9 and34.Last ReservedShipmentNumberResponse:Returns the lastrange reserved.Their elementsand furtherdescription canbe found inTable 10.Fig.13. Last Reserved Shipment Number Structure ResponseAramex International Shipping Information19
Your guide to embedding Aramex’sShipping API1.7Schedule Delivery MethodTable 8: Schedule Delivery Request & :This methodallows you toschedule thedelivery of ashipment at aspecified timeand place(Longitude andLatitude)Their elementsand furtherdescription canbe found inTable 9 and35.Fig.14. Scheduled Delivery Structure RequestAramex International Shipping Information20
Your guide to embedding Aramex’sShipping APIScheduledDeliveryResponse:Returns areference ID ofthe scheduleddelivery.Their elementsand furtherdescription canbe found inTable 10.Fig.15. Scheduled Delivery Structure ResponseAramex International Shipping Information21
Your guide to embedding Aramex’sShipping API2 Elements Data structure2.1General Request ElementsThese elements are present in all the methods of Shipping Services API (shipment creation,printing label, pickup creation and pickup cancellation), in addition to other specified elements.Table 9: General Request Elements - Client Info & TransactionDiagramDescriptionClient Info:The Client Info element is present in all the methods of thisservice.All its child elements are required to be filled.The user name and password are validated to allowaccess to the service.Version element, is the Version of the API the customer isusing, which needs to be specified in the requestAccount Number, Pin, Entity and Country Code are allneeded to verify the users account and obtain vitalinformation from it, such as the ability to create third partyshipments among other features provided for each account.Source, used for data mining purposes.For a more detailed description of the elements refer toTable 16.Fig.16. Client Info Structure DiagramAramex International Shipping Information22
Your guide to embedding Aramex’sShipping APITransaction:The Transaction element is not validated and is also presentin all the method requests and returned in all theirresponses for identification purposes.Any type of data can be included by the customer.For a more detailed description of the elements refer toTable 17.Fig.17. Transaction Structure DiagramAramex International Shipping Information23
Your guide to embedding Aramex’sShipping API2.2General Response ElementsThe Response of any method has three standard elements (notification, transaction, HasErrors)Table 10: General Response ElementsDiagramDescriptionNotification:Contains details of the request errors or success.Code To Identify the notification category.Message Deeper description of the Notification.Fig.18. Notification Structure DiagramTransaction:Contains the data sent in the request by the user, usedmainly for identification purposes.Fig.19. Transaction Structure DiagramHasErrors:Returns True if there are errors and false if there aren’t.Fig.20. Has Errors Structure DiagramAramex International Shipping Information24
Your guide to embedding Aramex’sShipping API2.3Shipment Creation ElementsThe request and response elements of the Shipment Creation method are described in the tablesbelow:Table 11: Shipment Creation Request ElementsDiagramDescriptionShipment:Required –Shipper, Consignee,and Details.Further details onshipment childelements are shownin Table 22Fig.21. Shipment Structure DiagramAramex International Shipping Information25
Your guide to emb
Shipping API Main Functionalities Creating shipments Allows you to create shipments, providing a wide range of options for customers to provide full details about their shipments, such as: 1. Attaching additional documentation: a) Clients can attach Performa Invoices, clearance forms
