Calidus Portal Web Service - TTM
A SOAP web service exists within the Calidus Portal application.
For the TTM module, the following methods are available:
| Method Name | Description |
| getInfo | Returns basic information for the system i.e. system name and version. This can be used to test access to the Web Service |
| getTrip | Returns Trip information (and additionally Stop, Order, Order Detail and Pallet information) * |
| getOrder | Returns Order information (and additionally Order Detail and Pallet information) * |
- These methods can be configured to include/exclude specific tags in the response.
Request Header
On all requests made to the Calidus Portal Web Service, a SOAP header will be required supplying a Username and Password.
The username and password used should correspond to a valid login account on the Calidus Portal system. The login information will be used to set the restrictions that the response will use to return the data i.e. the user's group will determine the restrictions setup against the user and these will be used (as they are in the actual TTM system) to restrict the data that the user can see. Any valid username/password can be used, including users where no restrictions have been added.
Response Header
The Response Header will be included on all responses from the Calidus Portal Web Service.
| Parameter | Data Type | Format | Description |
| <response_id> | xs:string | A35 | A unique ID for the web service response. This code (along with the response_datestamp) can be used to identify requests in the log files. |
| <response_datestamp> | xs:dateTime | XML Date/Time | A string date representing the time of the response as recorded on the logging table. |
| <response_code> | xs:int | 999 | The response code for the request. A return of 0 denotes a successful request/response and a return greater than 0 denotes an error. See section 10.1.6 for a complete list of codes and descriptions. |
| <response_code_desc> | xs:string | A50 | The description of the response. |
| <record_count> | xs:int | 99999 |
A count of the number of records contained in the response for the given method:
|
An example response header will be as follows:
<responseHdr> <response_id>befc95d5-5a74-4ecb-a3c5-91242ede3619</response_id> <response_datestamp>2015-12-31 00:00:00</response_datestamp> <response_code>0</response_code> <response_code_desc>OK</response_code_desc> <record_count>1</record_count> </responseHdr>
Response Field Configuration
The response returned from the web service will utilise the Calidus Portal Page Configuration to allow every field (with the exception of a few key fields where the show/hide and group types fields will be disabled) within the response to be returned or hidden.
The user can select 'Web Service' from the 'Search By' options, select the relevant module (TTM), the method they wish to configure (getTrip or getOrder) and then the section within the message e.g. TRIP, ORDER, REASON, ADDRESS etc. The page will then display all of the available fields in sequence within that section and the user can then choose whether to show (include) or hide (exclude) individual elements from the response.
Notes: The <detail_level> on the message will determine the detail level of the response, not the show/hide configuration.
Sections such as ORDER which can appear on both getTrip and getOrder may be configured separately for each method.Marking a whole section e.g. <pallet_details> as hidden will override any individual show settings within that section.
Method: getTrip
The getTrip method can be used to retrieve trip, stop and order information from the Calidus Portal.
Request Details
| Parameter | Data Type | Format | Description |
|---|---|---|---|
| <detail_level> | xs:string | A1 |
The detail level of the Response:
|
| <trip_id> | xs:string | A20 | A manifest no. that identifies a specific trip within the system |
| <trip_status> | xs:string | A12 |
A valid trip status:
|
| <trip_schedule> | xs:string | YYMMDD | |
| <owning_depot> | xs:string | A12 |
Note: A valid request header is required.
Validation - At least one of the parameters trip_id, trip_status or schedule must be supplied.
Additionally, if trip_status is "COMPLETED" then a schedule (or trip_id) must also be supplied. Owning depot is always optional.
Date limitation - If a schedule isn't supplied then a limit of 5000 trips will be imposed or 1000 if orders are requested. If a schedule is supplied all trips/orders on the schedule (dependent on other filter criteria) will be supplied. If the limit is exceeded a status of '2 - Record Limit Exceeded' will be returned with no trip records.
Response Details
<TRIP> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <trip_id> | xs:string | A20 | A manifest no. that identifies a specific trip within the system |
| <haulier> | xs:string | A12 | The ID of the haulier assigned to the trip |
| <haulier_name> | xs:string | A50 | The name of the haulier assigned to the trip |
| <haulier_contact> | xs:string | A100 | The contact details for the haulier |
| <driver> | xs:string | A10 | The ID of the driver assigned to the trip |
| <driver_name> | xs:string | A50 | The name of the driver assigned to the trip |
| <driver_contact> | xs:string | A12 | The contact details for the driver |
| <tractor> | xs:string | A12 | The tractor assigned to the trip |
| <trip_trailer_id> | xs:string | A12 | The trailer assigned to the trip |
| <trip_trailer_type> | xs:string | A12 | The type of the trailer |
| <trip_status> | xs:string | A12 | Trip status - ABANDONED, ACCEPTED, COMPLETED, DELETED, EN-ROUTE, PLANNED |
| <trip_start_date> | xs:dateTime | XML Date/Time | The trip start date |
| <trip_lat> | xs:double | Signed Degrees | The Latitude for the current truck position |
| <trip_lon> | xs:double | Signed Degrees | The Longitude for the current truck position |
| <trip_ref> | xs:string | A20 | The reference for the trip |
| <owning_depot> | xs:string | A12 | The owning depot responsible for the trip |
| <gdp_trailer> | xs:string | A1 | Y/N denoting if a GDP trailer is required |
| <trip_schedule> | xs:string | YYMMDD | The Calidus TMS schedule for the trip |
| <last_updated> | xs:dateTime | XML Date/Time | The date/time of the last trip update on the Calidus Portal system |
| <trip_reasons> | tns:reasons | A section containing any TRIP level reasons held on the Calidus Portal. See <REASON> section. Note: Not currently used for Consumer. | |
| <stops> | tns:stops | A section containing the stops on the order. See <STOP> section. |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
<STOP> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <stop_seq> | xs:int | 99 | |
| <stop_pid> | xs:string | A6 | The unique Trip/Stop PID as supplied by Calidus TMS |
| <stop_type> | xs:string | A2 | The stop type as supplied by Calidus TMS - SU,PK,DL,CL |
| <stop_address> | tns:address | Section containing the stop address. See <ADDRESS> section. | |
| <planned_arr_date> | xs:dateTime | XML Date/Time | |
| <current_arr_date> | xs:dateTime | XML Date/Time | |
| <actual_arr_date> | xs:dateTime | XML Date/Time | |
| <planned_dep_date> | xs:dateTime | XML Date/Time | |
| <actual_dep_date> | xs:dateTime | XML Date/Time | |
| <signed_by> | xs:string | A30 | |
| <signature> | xs:string | A20000 | A Base64 encoded string containing the image of the signature |
| <stop_reasons> | tns:reasons | A section containing any STOP level reasons held on the Calidus Portal. See <REASON> section. Note: Not currently used for Consumer | |
| <orders> | tns:orders |
Section containing the orders within the stop. See <ORDER> section within the getOrder method for details. |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
<ADDRESS> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <address_type> | xs:string | A3 | The type of the address - COL/DEL |
| <address_id> | xs:string | A20 | The ID of the address |
| <name> | xs:string | A50 | The name associated with the address |
| <line1> | xs:string | A50 | The first line of the address |
| <line2> | xs:string | A50 | The second line of the address |
| <line3> | xs:string | A50 | The third line of the address |
| <line4> | xs:string | A50 | The fourth line of the address |
| <line5> | xs:string | A50 | The fifth line of the address |
| <post_code> | xs:string | A9 | The postcode |
| <country_code> | xs:string | A3 | The data held in the country code field of the address |
| <contact_name> | xs:string | A101 | The contact name |
| <contact_number> | xs:string | A50 | The contact phone number |
| <address_lat> | xs:double | Signed Degrees | The Latitude for the address |
| <address_lon> | xs:double | Signed Degrees | The Longitude for the address |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
<REASON> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <reason_type> | xs:string | A5 | The type of the reason code |
| <reason_code> | xs:string | A12 | The reason code |
| <reason_desc> | xs:string | A50 | The description of the reason code |
| <reason_comment> | xs:string | A100 | The comment included with the reason |
| <reason_qty> | xs:int | -99999999 |
The quantity associated with the reason code. Note: This field is currently only supplied on ITEM (Order Detail) level reasons. |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
Method: getOrder
The getOrder method can be used to retrieve order information from the Calidus Portal.
Request Details
| Parameter | Data Type | Format | Description |
|---|---|---|---|
| <detail_level> | xs:string | A1 |
The detail level of the Response:
|
| <owner> | xs:string | A12 | A single owner code |
| <so_ref> | xs:string | A20 | A single system order number |
| <po_ref> | xs:string | A50 | A single PO Reference |
| <book_ref> | xs:string | A50 | A single Booking Reference |
| <tms_ref> | xs:string | A50 | A single Calidus TMS Reference |
| <warehouse_id> | xs:string | A6 | The warehouse id from which the order originates |
| <so_status> | xs:string | A3 | A single Order Status e.g. ORD, ALC, MAR, LOA, DEL, CAN |
| <order_date_from> | xs:dateTime | XML Date/Time | The start of a date range for the ordered date against orders. If supplied, then a 'book date to' must also be supplied. The ordered date is the date the order was placed. |
| <order_date_to> | xs:dateTime | XML Date/Time | The end of a date range for the ordered date against orders. If supplied, then a 'book date from' must also be supplied and the 'from date' must be less than the 'to date' |
| <book_date_from> | xs:dateTime | XML Date/Time | The start of a date range for the booked date against orders. If supplied, then a 'book date to' must also be supplied. The search will be against the latest booking dates. |
| <book_date_to> | xs:dateTime | XML Date/Time | The end of a date range for the booked date against orders. If supplied, then a 'book date from' must also be supplied and the 'from date' must be less than the 'to date' |
| <conf_date_from> | xs:dateTime | XML Date/Time | The start of a date range for the conf date against orders. If supplied, then a 'conf date to' must also be supplied. The conf date is the Delivery date of the order. |
| <conf_date_to> | xs:dateTime | XML Date/Time | The end of a date range for the conf date against orders. If supplied, then a 'conf date from' must also be supplied and the 'from date' must be less than the 'to date' |
Note: A valid request header is required.
Validation - One of the reference fields (so_ref, po_ref, tms_ref or book_ref) or one of the date ranges (order_date, book_date, conf_date) must be supplied. If supplied, the date ranges may be no more than 31 days.
Data Limitation - A limit of 10000 order records will be imposed. If the limit is exceeded a status of '2 - Record Limit Exceeded' will be returned with no order records.
Response Details
<ORDER> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <owner> | xs:string | A12 | The owner code of the order |
| <so_ref> | xs:string | A20 | The ID of the haulier assigned to the trip |
| <addresses> | tns:addresses | Section containing the collection and delivery address of the order. See <ADDRESS> section. NOTE: It is recommended that the system is configured so that if the method is getTrip then this section will be excluded as the address will be against the stop. By default, it will appear. | |
| <so_status> | xs:string | A3 | The current status code of the order |
| <status_desc> | xs:string | A50 | The current status description of the order |
| <warehouse_id> | xs:string | A6 | The warehouse id from which the order originates |
| <po_ref> | xs:string | A50 | The PO ref of the order |
| <book_ref> | xs:string | A50 | The booking ref of the order |
| <tms_ref> | xs:string | A50 | The Calidus TMS ref of the order |
| <customer_id> | xs:string | A15 | The Customer Id of the order (if supplied - currently not for Consumer) |
| <customer_name> | xs:string | A50 | The name associated with the Customer ID |
| <collection_trip> | xs:string | A20 | The Trip ID for the collection of the order |
| <collection_stop> | xs:int | 99 | The Stop Sequence for the collection of the order |
| <delivery_trip> | xs:string | A20 | The Trip ID for the delivery of the order |
| <delivery_stop> | xs:int | 99 | The Stop Sequence for the delivery of the order |
| <book_date> | xs:dateTime | XML Date/Time | The latest booking date held against the order |
| <arrival_date> | xs:dateTime | XML Date/Time | The arrival date held against the order for the delivery stop |
| <departure_date> | xs:dateTime | XML Date/Time | The departure date held against the order for the delivery stop |
| <delivery_date> | xs:dateTime | XML Date/Time | The delivery (conf) date held against the order for the delivery stop |
| <delivery_user> | xs:string | A30 | The delivery (conf) user held against the order for the delivery stop |
| <special_instructions> | xs:string | A250 | Special instructions held against the order |
| <order_comments> | xs:string | A250 | Order comments held against the order |
| <gdp_trailer> | xs:string | A1 | Y/N denoting if a GDP trailer is required |
| <lift_count> | xs:decimal | 99999999.99 | A count of the total lifts on the order |
| <qty_count> | xs:int | 999999999 | A count of the total quantity ordered on the order |
| <pallet_count> | xs:int | 999999999 | A count of the total pallets on the order |
| <line_count> | xs:int | 999999999 | A count of the number of order detail lines |
| <order_reasons> | tns:reasons | A section for ORDER level reasons held on the Calidus Portal. See <REASON> section. Note: Not currently used for Consumer. | |
| <order_details> | tns:order_details | A section containing the orders stock details. See <ORDER_DETAIL> section. |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
<ORDER_DETAIL> Section
| Field Name | Data Type | Format | Description | Example |
|---|---|---|---|---|
| <item_id> | xs:string | A50 | The stock code | 8019008 |
| <item_description> | xs:string | A100 | The description of the stock code | VANSH 100ML NOR X50 |
| <qty_ordered> | xs:int | 999999999 | The ordered quantity against the order line | 123 |
| <qty_packed> | xs:int | 999999999 | The picked/packed quantity against the order line | 123 |
| <qty_to_deliver> | xs:int | 999999999 | The to deliver (despatched) quantity against the order line | 123 |
| <qty_delivered> | xs:int | 999999999 | The delivered quantity against the order line | 123 |
| <item_height> | xs:decimal | 999999999.9999 | The item height stored against the order line | 123.4567 |
| <item_width> | xs:decimal | 999999999.9999 | The item width stored against the order line | 123.4567 |
| <item_length> | xs:decimal | 999999999.9999 | The item length stored against the order line | 123.4567 |
| <item_weight> | xs:decimal | 999999999.99999 | The weight stored against the order line | 123.45678 |
| <item_volume> | xs:decimal | 999999999.99999 | The volume stored against the order line | 123.45678 |
| <item_factor> | xs:int | 999999999 | The unit of sale factor stored against the order line | 10 |
| <factor_1_2> | xs:int | 999999 | The 'unit to case' factor | 10 |
| <factor_1_3> | xs:int | 999999 | The 'unit to pallet' factor | 500 |
| <factor_2_3> | xs:int | 999999 | The 'case to pallet' factor | 50 |
| <case_layer> | xs:int | 999999 | The 'case per layer' factor | 10 |
| <product_type_desc> | xs:string | A12 | The description of the product type of the stock code | AMBIENT |
| <item_reasons> | tns:reasons | A section containing any ITEM level reasons held on the Calidus Portal. See <REASON> section. | ||
| <pallet_details> | tns:pallets | A section containing pallet details for the stock code, if available on the Calidus Portal. See <PALLET_DETAIL> section. |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
<PALLET_DETAIL> Section
| Field Name | Data Type | Format | Description |
|---|---|---|---|
| <order_line_no> | xs:int | 999 | |
| <pick_location> | xs:string | A20 | |
| <pick_pallet_id> | xs:int | 99999999 | |
| <rotation_no> | xs:string | A30 | |
| <cust_rotation_no> | xs:string | A30 | |
| <cust_pallet_id> | xs:string | A30 | |
| <sell_by_date> | xs:dateTime | XML Date/Time | |
| <manufacture_date> | xs:dateTime | XML Date/Time | |
| <qty_to_deliver> | xs:int | 999999999 | |
| <qty_despatched> | xs:int | 999999999 | |
| <picker> | xs:string | A4 | |
| <checker> | xs:string | A4 | |
| <pick_date> | xs:dateTime | XML Date/Time | |
| <picking_reason_code> | xs:string | A4 | |
| <despatch_date> | xs:dateTime | XML Date/Time | |
| <despatch_user> | xs:string | A4 | |
| <despatch_reason_code> | xs:string | A4 |
Note: Fields will only be sent on the response if they have been populated within the Calidus Portal.
Response Codes
| Code | Message |
|---|---|
| 0 | OK |
| 1 | Invalid or Missing Credentials |
| 2 | Record Limit Exceeded |
| 3 | Invalid Parameters |
| 999 | webService Error |
