Krengel Ship for UPS Rating Request
From Wiki
|
| User Guide |
Contents |
Overview
The Krengel Ship for UPS Rate Request API allows you to compare prices and select shipping services that best fit specific timelines and budgets. Use this in combination with the Time in Transit API to first obtain a list of services and then determine cost to ship by a specific service code. Rate requests return data such as total rate charge, delivery days, and specific delivery time.
Example 1
This example goes through the process of rating a package shipment. Note that this example is occupying the minimum required fields to rate a shipment with UPS.
Rating Request API Example, Ship From Address
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 pages.
Rating RequestAPI Example, Ship To Address
Rating RequestAPI Example, Shipping Options Screen
Lastly, we'll add our package. To add new packages, or to view previously entered packages, use Page Up or Page Down.
Rating Request API Example, Package Screen, Package 1
Pressing Enter will submit this request to the UPS Rating Request API, and return a response as shown below:
Rating Request API Example, Response (Shipment Level)
You should see a results screen subfile similar to the one above. Page Up and Page Down Fill the View Package Level Results field with an X, and press Enter - this allows you to see the ratings for individual packages.
Rating Request API Example, Response (Package Level)
Technical Information
This API section in UPSUI is making use of the following elements:
Request Tables
The request data is stored in two physical files: UPSRTRQ and UPSRTRQPK.
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_ratingReq. UIDs are generated using UPS_getUID. |
| USERID | 30 characters | UPS OnLine Tools ID | Required. Contains a user ID stored in UPSUSER. |
| ACCTNBR | 10 characters | UPS Shipper Account Number | Required. This field must contain the UPS Shipper Number for a UPS account that exists in UPSACCT. |
| REQOPT | 4 characters | Request Option Type | Required. This field can be set to RATE or SHOP. If RATE, field SVCCD must have a value, and UPS will return only results for the specified UPS Service Code. If SHOP, UPS will return results for multiple Service Codes. |
| PKUPCD | 2 characters | Pickup Type Code | Valid values are:
|
| CSTCLSCD | 2 characters | Customer Classification | Valid values are:
|
| STCONAME | 35 characters | Ship To Company Name | Almost never used. |
| STADDR1 | 35 characters | Ship To Address Line 1 | |
| STADDR2 | 35 characters | Ship To Address Line 2 | |
| STADDR3 | 35 characters | Ship To Address Line 3 | |
| 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. |
| SFCONAME | 35 characters | Ship From Company Name | Almost never used. |
| SFADDR1 | 35 characters | Ship From Address Line 1 | |
| SFADDR2 | 35 characters | Ship From Address Line 2 | |
| SFADDR3 | 35 characters | Ship From Address Line 3 | |
| 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. |
| SVCCD | 4 characters | UPS Service Code | UPS Service Code. This field is only needed when REQOPT is set to RATE. This field may be used with smart defaulting. |
| 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. |
| SATPKUP | 1 character | Require Saturday Pickup | If Saturday Pickup is required, this field should be populated with a true value. |
| SATDLVR | 1 character | Require Saturday Delivery | If Saturday Delivery is required, this field should be populated with a true value. |
| PKUPDAY | 2 characters | Pickup Day Code | |
| PKUPMTHD | 2 characters | Pickup Method | |
| CNEUTRAL | 1 character | Carbon Neutral Shipment | If you wish UPS to add a carbon neutral shipment surcharge, this field should be populated with a true value. |
| DELCNFCD | 1 character | Delivery Confirmation Type Code | |
| NEGRATE | 1 character | Negotiated Rate Indicator | If you wish UPS to return negotiated rates, this field should be populated with a true value. |
| INVCURCD | 3 character | Invoice Currency Code | |
| INVVALUE | 10,2 packed | Invoice Value |
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_ratingReq. UIDs are generated using UPS_getUID. There should be a record in UPSRTRQ with a UID equal to this field's value. |
| UID | 15,0 packed | Child Unique ID | Key. This is used to uniquely identify a package within a request. UIDs are generated using UPS_getUID. |
| PKGCD | 2 characters | Packaging Type Code | |
| DIMCD | 2 characters | Package Dimension Code | |
| LENGTH | 6,2 packed | Package Length | |
| WIDTH | 6,2 packed | Package Width | |
| HEIGHT | 6,2 packed | Package Height | |
| WGTCD | 3 characters | Weight Code | |
| PKGWGT | 8,2 packed | Package Weight | |
| LRGPKG | 1 character | Large Package Indicator | This field should be populated with a true value when the package LENGTH plus girth [(2 x WIDTH) + (2 x HEIGHT)] combined exceeds 130 inches, but does not exceed the maximum UPS size of 165 inches. If left empty, UPS will populate it automatically if required. |
| INSCURCD | 3 characters | Insured Value Currency Code | |
| INSVALUE | 15,2 packed | Insured Value | |
| CODFNDCD | 1 character | COD Funds Code | |
| CODCURCD | 3 characters | COD Currency Code | |
| CODVALUE | 8,2 packed | COD Value | |
| DELCNFCD | 1 character | Delivery Confirmation Type Code | |
| VRBCNFNM | 35 characters | Verbal Confirmation Name | |
| VRBPHONE | 15 characters | Verbal Confirmation Phone Number | |
| ADDLHNDL | 1 character | Additional Handling Required | If this package requires additional handling, this field should be populated with a true value. |
Response Table
The response data is stored in two physical files: UPSRTRS and UPSRTRSPK.
Table Structure
| Name | Data Type | Description | Notes |
|---|---|---|---|
| PID | 15,0 packed | Parent Unique ID | |
| UID | 15,0 packed | Child Unique ID | |
| SVCCD | 4 characters | UPS Service Code | |
| SVCDSC | 40 characters | UPS Service Code Description | |
| WGTCD | 3 characters | Shipment Weight Code | |
| TOTWGT | 8,2 packed | Shipment Weight | |
| TRSCURCD | 3 characters | Transportation Charges Currency Code | |
| TRSCHRG | 15,2 packed | Transportation Charges | |
| SVCCURCD | 3 characters | Service Currency Code | |
| SVCCHRG | 15,2 packed | Service Charge | |
| TOTCURCD | 3 characters | Total Currency Code | |
| TOTCHRG | 15,2 packed | Total Charge | |
| GTDDAYS | 8 characters | Guaranteed Days to Delivery | |
| GTDTIM | Time | Guaranteed Delivery Time | |
| NEGCURCD | 3 characters | Negotiated Currency Code | |
| NEGCHRG | 15,2 packed | Negotiated Total Charges |
| Name | Data Type | Description | Notes |
|---|---|---|---|
| PID | 15,0 packed | Parent Unique ID | |
| UID | 15,0 packed | Child Unique ID | |
| TRSCURCD | 3 characters | Trans. Currency Code | |
| TRSCHRG | 15,2 packed | Transportation Charge | |
| SVCCURCD | 3 characters | Service Currency Code | |
| SVCCHRG | 15,2 packed | Service Charge | |
| PKGCURCD | 3 characters | Package Currency Code | |
| PKGCHRG | 15,2 packed | Package Charge | |
| WGTCD | 3 characters | Package Weight Code | |
| PKGWGT | 8,2 packed | Package Weight | |
| BILLWGT | 8,2 packed | Package Billing Weight |
API Function
The Krengel Ship for UPS API function used is UPS_ratingReq.
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 UPSRTRQ.
- Insert a record into UPSRTRQ.
- For each package, call UPS_getUID to get the UID that will be used to store and identify the record in UPSRTRQPK.
- Insert each package into UPSRTRQPK.
- Call UPS_ratingReq, passing the UID used when writing to UPSRTRQ and the Krengel Ship for UPS Error Data Structure.
- The UPS_ratingReq API will send the request to the UPS web service, and will store the response in UPSRTRS and UPSRTRSPK.
- 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 UPSRTRS and UPSRTRSPK.