Krengel Ship for UPS Time in Transit
From Wiki
|
| User Guide |
Contents |
Overview
The Krengel Ship for UPS Time in Transit API allows you to provide address and shipment information. UPS will then use this information to create a list of available shipping services with the estimated delivery dates.
Example
Time in Transit with sample Addresses
Pressing Enter will move you to the next screen. Alternatively, you can change the number in the bottom right of the screen to move between screens.
Time in Transit, Shipment Information
Pressing Enter will submit this request to the UPS Time in Transit API, and return a response as shown below:
Time in Transit Example response
Technical Information
This API section in UPSUI is making use of the following elements:
Request Tables
The request data is stored in UPSTTRQ.
Table Structure
| Name | Data Type | Description | Notes |
|---|---|---|---|
| UID | 15,0 packed | Record Unique ID | Key. This is used to uniquely identify a request. This UID corresponds to the UID passed as the first parameter to UPS_timeInTransit. UIDs are generated using UPS_getUID. |
| USERID | 30 characters | UPS OnLine Tools ID | Required. Contains a user ID stored in UPSUSER. |
| STTOWN | 30 characters | Ship To Town | Not used for requests within the United States. |
| STCITY | 40 characters | Ship To City | |
| STSTATE | 5 characters | Ship To State | For US addresses, use the 2 character abbreviations used by the US Postal Service. For international addresses, follow the abbreviation standards of the country. |
| STPOSTCD | 16 characters | Ship To Postal Code | For US addresses, use the Zip Code with the +4 code if available. For international addresses, use the postal code system of the country. |
| STCNTRY | 2 characters | Ship To Country Code | For all addresses, use the Alpha-2 abbreviation specified in ISO 3166-1. Note that currently, only US, PR, and CA are valid. |
| STRESDNT | 1 character | Residential Indicator | If this address is residential, this field should be populated with a true value. |
| SFTOWN | 30 characters | Ship From Town | Not used for requests within the United States. |
| SFCITY | 40 characters | Ship From City | |
| SFSTATE | 5 characters | Ship From State | For US addresses, use the 2 character abbreviations used by the US Postal Service. For international addresses, follow the abbreviation standards of the country. |
| SFPOSTCD | 16 characters | Ship From Postal Code | For US addresses, use the Zip Code with the +4 code if available. For international addresses, use the postal code system of the country. |
| SFCNTRY | 2 characters | Ship From Country Code | For all addresses, use the Alpha-2 abbreviation specified in ISO 3166-1. Note that currently, only US, PR, and CA are valid. |
| WGTCD | 3 characters | Weight Code | Code used for the weight of the package. The valid values are LBS for Pounds, and KGS for Kilograms. This field may be used with smart defaulting. |
| WGT | 5,2 packed | Weight | Total weight of all packages in the shipment. This weight cannot exceed 150 LBS, or 70 KGS. |
| TOTPKGS | 10,0 packed | Packages in Shipment | If left empty, UPS will assume 1 package. |
| PKUPDT | Date | Pickup Date | This field is *ISO format, and will default to 0001-01-01 when this record is written if this field is left empty. |
| CURCD | 3 characters | Currency Code | This field is required if field VALUE has a non-zero value. |
| VALUE | 11,2 packed | Monetary Value | Total monetary value of all packages in the shipment. If this field has a non-zero value, field CURCD must be populated with a valid Currency Code. |
| DOCONLY | 1 character | Documents Only | If this field has a true value, you are indicating to UPS that all packages in this shipment are documents. If this field has a false value, or is blank, UPS will treat this request as though it contains packages. Either of these may alter the returned results. |
| RESULTS | 2,0 packed | # of Results Returned | This controls how many possible results UPS will return. This number can be between 1 and 50. If left empty, UPS will default to 35. |
Response Table
The response data is stored in UPSTTRS.
Table Structure
| Name | Data Type | Description | Notes |
|---|---|---|---|
| PID | 15,0 packed | Parent Unique ID | Key. This is used to uniquely identify a request. This UID corresponds to the UID passed as the first parameter to UPS_timeInTransit. UIDs are generated using UPS_getUID. |
| UID | 15,0 packed | Child Unique ID | Key. This is used to uniquely identify a result from a response. UIDs are generated using UPS_getUID. |
| SVCCD | 4 characters | UPS Service Code | Service code returned from UPS. Note that for unknown reasons, the service codes returned from UPS by this API differ from codes used in other APIs such as UPS_shipConfirm and UPS_ratingReq. For example, UPS Ground is generally a value of 03 in UPS_shipConfirm, but in this API, UPS Ground is returned as GND. |
| SVCDSC | 50 characters | UPS Service Description | Text description of the SVCCD field. |
| GRNTEED | 1 character | Guaranteed Shipment | If this contains a true value, UPS has indicated that the delivery times and dates are Guaranteed. |
| DOCONLY | 1 character | Documents Only | If this contains a true value, UPS has indicated that this response is for Documents Only. |
| AUTDTYCD | 2 characters | Auto Duty Code | This will be returned for requests involving international addresses. If DOCONLY in UPSTTRQ was a true value, this field will have one of the following values:
|
| WEEKDAY | 3 characters | Estimated Arrival Day of Week | 3 character day abbreviation. Possible values:
|
| ARRIVTIM | Time | Estimated Arrival Time | Arrival Time is in *HMS format. |
| ARRIVDT | Date | Estimated Arrival Date | Arrival Date is in *ISO format. |
| PKUPTIM | Time | Pickup Time | Pickup Time is in *HMS format. |
| PKUPDT | Date | Pickup Date | Pickup Date is in *ISO format. |
| TRANSBUS | 2,0 packed | Business Transit Days | Number of business days the shipment will be in transit |
| TRANSTOT | 2,0 packed | Total Transit Days | Total number of days the shipment will be in transit. |
| CUTOFF | Time | Customer Cutoff Time | |
| RESTDAYS | 2,0 packed | Non-Movement Days | Number of days package will be held up. Generally only returned for requests involving international addresses. |
| HOLIDAYS | 2,0 packed | Holidays Delay | Number of days package will be held up due to national holidays. Generally only returned for requests involving international addresses. |
| CUSTOMS | 2,0 packed | Customs Delay | Number of days package will be held up due to Customs. Generally only returned for requests involving international addresses. |
API Function
The Krengel Ship for UPS API function used is UPS_timeInTransit.
Technical Example
This is a brief explanation of how this API is implemented in the included Krengel Ship for UPS User Interface program. You can use the source code for the Krengel Ship for UPS User Interface combined with this example to implement the API in your existing business programs.
- Define the Krengel Ship for UPS Error Data Structure.
- Call UPS_getUID to get the UID that will be used to store and identify the record in UPSTTRQ.
- Insert a record into UPSTTRQ with a valid combination of data (explained above).
- Call UPS_timeInTransit, passing the UID and the Krengel Ship for UPS Error Data Structure.
- The UPS_timeInTransit API will send the request to the UPS web service, and will store the response in UPSTTRS.
- Check the Krengel Ship for UPS Error Data Structure to see if an error occurred. If an error did not occur, you may read the records out of UPSTTRS - field PID will be the UID used to call UPS_timeInTransit.