Krengel Ship for UPS Package Shipping
From Wiki
|
| User Guide |
Contents |
Overview
The Krengel Ship for UPS Shipping APIs (ShipConfirm, ShipAccept, and ShipVoid) allow you to create and void (cancel) shipments with UPS.
This sequence of screens demonstrates the UPS Ship Confirm and UPS Ship Accept APIs. More about UPS Ship Void can be read here.
Note that this example program is primarily for shipping within the United States (US), Puerto Rico (PR), and Canada (CA). Shipping outside of these regions will generally require international shipping forms, which are not implemented in this example program. However, they can be implemented using physical files UPSSCRQFM and UPSSCRQPD. More about international shipping can be found here.
Example
This example goes through the process of creating a 3 package shipment. Note that this example is occupying the minimum required fields to create a shipment with UPS, with the exception that 3 packages are being shipped. A shipment can and frequently will only have a single package.
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.
The above image demonstrates the usage of the UPSUI prompting function. You can move your cursor to the Service Code field, and press F4. This will open the Prompt window. You can select a value from the list with an X in the leftmost field, and press Enter. The Service Code field will populate based upon your selection. Promptable fields appear in most UPSUI screens, and are indicated by a blue question mark (?).
Lastly, we'll add our three packages. We'll prompt the Packaging Type Code for the first package, but for subsequent packages, we'll enter the values without prompting. To add new packages, or to view previously entered packages, use Page Up or Page Down.
Pressing Enter will submit this request to the UPS Shipment Confirm API, and return a response as shown below:
To confirm the shipment, press Y, and then Enter.
You should see a results screen subfile similar to the one above. At this point, you can print out your shipping labels, which are located at the IFS path specified in field LBLIMG in physical file UPSSARSPK for each package.
Technical Information
This API section in UPSUI is making use of the following elements:
API Function
This screen is different in that it actually uses two Krengel Ship for UPS API functions: first, UPS_shipConfirm is used to begin a shipment, and UPS_shipAccept is used to authorize UPS to charge for the shipment, as well as return shipping labels and tracking numbers.
Request Tables
Because this uses two different Krengel Ship for UPS functions, there are more physical files. Note, however, that there are not request files for the UPS_shipAccept API. This is because the information used to perform a UPS_shipAccept request is all found in the response tables for UPS_shipConfirm.
Table Structure - UPSSCRQ
| Name | Data Type | Description | Notes |
|---|---|---|---|
| UID | 15,0 packed | Record Unique ID | |
| USERID | 30 characters | UPS User ID | |
| ACCTNBR | 10 characters | UPS Account Number | |
| SHIPDESC | 35 characters | Shipment Description | |
| STCONAME | 35 characters | Ship To Comp. Name | |
| STATNAME | 35 characters | Ship To Attn. Name | |
| STTAXID | 15 characters | Ship To Tax ID Nbr. | |
| STPHONE | 15 characters | Ship To Phone Nbr. | |
| STFAX | 15 characters | Ship To Fax Nbr. | |
| STEMAIL | 50 characters | Ship To Email Address | |
| STADDR1 | 35 characters | Ship To Address 1 | |
| STADDR2 | 35 characters | Ship To Address 2 | |
| STADDR3 | 35 characters | Ship To Address 3 | |
| STCITY | 40 characters | Ship To City | |
| STSTATE | 5 characters | Ship To State | |
| STPOSTCD | 16 characters | Ship To Postal CD | |
| STCNTRY | 2 characters | Ship To Country | |
| STRESDNT | 1 character | Y or T = Residential | |
| SFCONAME | 35 characters | Ship From Comp. Name | |
| SFATNAME | 35 characters | Ship From Attn. Name | |
| SFTAXID | 15 characters | Ship From Tax ID Nbr. | |
| SFPHONE | 15 characters | Ship From Phone Nbr. | |
| SFFAX | 15 characters | Ship From Fax Nbr. | |
| SFEMAIL | 50 characters | Ship From Email Address | |
| SFADDR1 | 35 characters | Ship From Address 1 | |
| SFADDR2 | 35 characters | Ship From Address 2 | |
| SFADDR3 | 35 characters | Ship From Address 3 | |
| SFCITY | 40 characters | Ship From City | |
| SFSTATE | 5 characters | Ship From State | |
| SFPOSTCD | 16 characters | Ship From Postal CD | |
| SFCNTRY | 2 characters | Ship From Country | |
| VALIDATE | 1 character | Validate Addresses | |
| BILLTYPE | 3 characters | Billing Type | Valid values are PBS (Prepaid Bill Shipper), BTP (Bill Third Party), FTC (Freight Collect), and CSB (Consignee Bill). |
| BACCTNBR | 10 characters | Billing Account Number | Used when Billing Type is BTP or FTC. Must be a valid UPS Shipper Number. |
| BPOSTCD | 15 characters | Billing Postal Code | Used when Billing Type is BTP or FTC. |
| BCNTRY | 2 characters | Billing Country Code | Used when Billing Type is BTP or FTC. |
| RETURNCD | 1 character | Return Service Code | |
| DOCONLY | 1 character | T or Y = Documents Only | |
| GNIFC | 1 character | T or Y = Goods Not Free Circ. | |
| NEGRATE | 1 character | T or Y = Negotiated Rt Ind. | |
| MVREFNBR | 18 characters | Movement Ref. Nbr. | |
| RF1BC | 1 character | T or Y = Ref. Nbr. 1 Barcode | |
| RF1CD | 2 characters | Ref. Nbr. 1 Code | |
| RF1VALUE | 35 characters | Ref. Nbr. 1 Value | |
| RF2BC | 1 character | T or Y = Ref. Nbr. 2 Barcode | |
| RF2CD | 2 characters | Ref. Nbr. 2 Code | |
| RF2VALUE | 35 characters | Ref. Nbr. 2 Value | |
| SVCCD | 4 characters | UPS Service Code | |
| LINCURCD | 3 characters | Inv. Line Total Currency Code | |
| LINVALUE | 8,0 packed | Inv. Line Total Value | |
| SATDLVR | 1 character | T or Y = Req Sat Deliver | |
| INVRMV | 1 character | T or Y = Remove Invoice Ind. | |
| CNEUTRAL | 1 character | T or Y = Carbon Neutral Ind. | |
| DELCNFCD | 1 character | Deliver Conf. Code | |
| LBLFMTCD | 6 characters | Ship Label Format Code | |
| INVFORM | 1 character | I = Full Invoice P = Partial | |
| SEDFORM | 1 character | T or Y = SED Form Ind. | |
| COFORM | 1 character | T or Y = CO Form Ind. | |
| NCOFORM | 1 character | T or Y = NCO Form Ind. |
Table Structure - UPSSCRQPK
| Name | Data Type | Description | Notes |
|---|---|---|---|
| PID | 15,0 packed | Parent Unique ID | |
| UID | 15,0 packed | Child Unique ID | |
| PKGRTN | 35 characters | Package Return Desc. | |
| PKGCD | 2 characters | Package Type Code | |
| DIMCD | 2 characters | Package Dim Code | |
| LENGTH | 6,2 packed | Package Length | |
| WIDTH | 6,2 packed | Package Width | |
| HEIGHT | 6,2 packed | Package Height | |
| WGTCD | 3 characters | Package Weight Code | |
| PKGWGT | 8,2 packed | Package Weight | |
| LRGPKG | 1 character | T or Y = Large Package Ind. | |
| RF1BC | 1 character | T or Y = Ref. Nbr. 1 Barcode | |
| RF1CD | 2 characters | Ref. Nbr. 1 Code | |
| RF1VALUE | 35 characters | Ref. Nbr. 1 Value | |
| RF2BC | 1 character | T or Y = Ref. Nbr. 2 Barcode | |
| RF2CD | 2 characters | Ref. Nbr. 2 Code | |
| RF2VALUE | 35 characters | Ref. Nbr. 2 Value | |
| ADDLHNDL | 1 character | T or Y = Add. Handling Req. | |
| DELCNFCD | 1 character | Delivery Conf Type Code | |
| DELNBR | 11 characters | Delivery Conf Control Nbr. | |
| INSVALCD | 3 characters | Insured Value Code | |
| INSCURCD | 3 characters | Insured Value Curr. 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 | |
| VRBCNFNM | 35 characters | Verbal Conf. Name | |
| VRBPHONE | 15 characters | Verbal Conf. Phone Nbr | |
| SHIPRLS | 1 character | T or Y = Shipper Release Ind. |
Response Tables
Because this uses two different Krengel Ship for UPS functions, there are more physical files. Note that there are two different sets of response tables - one set for UPS_shipConfirm, and a different set for UPS_shipAccept. Physical files beginning with UPSSCRS are the response files for UPS_shipConfirm, while UPSSARS indicates the response files are from UPS_shipAccept.
Ship Confirm Response
Table Structure - UPSSCRS
| Name | Data Type | Description | Notes |
|---|---|---|---|
| UID | 15,0 packed | Record Unique ID | |
| TRSCURCD | 3 characters | Trans. Currency Code | |
| TRSCHRG | 15,2 packed | Trans. Charge | |
| SVCCURCD | 3 characters | Service Currency Code | |
| SVCCHRG | 15,2 packed | Service Charge | |
| TOTCURCD | 3 characters | Total Currency Code | |
| TOTCHRG | 15,2 packed | Total Charge | |
| WGTCD | 3 characters | Shipment Weight Code | |
| TOTWGT | 8,2 packed | Shipment Weight | |
| SHIPNBR | 21 characters | Shipment ID Number | |
| NEGCURCD | 3 characters | Negotiated Curr. Code | |
| NEGCHRG | 15,2 packed | Negotiated Total Charges | |
| DIGEST | 256 characters | IFS Path to Digest |
Ship Accept Response
Table Structure - UPSSARS
| Name | Data Type | Description | Notes |
|---|---|---|---|
| UID | 15,0 packed | Record Unique ID | |
| TRSCURCD | 3 characters | Trans. Currency Code | |
| TRSCHRG | 15,2 packed | Trans. Charge | |
| SVCCURCD | 3 characters | Service Currency Code | |
| SVCCHRG | 15,2 packed | Service Charge | |
| TOTCURCD | 3 characters | Total Currency Code | |
| TOTCHRG | 15,2 packed | Total Charge | |
| NEGCURCD | 3 characters | Negotiated Curr. Code | |
| NEGCHRG | 15,2 packed | Negotiated Total Charges | |
| WGTCD | 3 characters | Shipment Weight Code | |
| TOTWGT | 8,2 packed | Shipment Weight | |
| SHIPNBR | 21 characters | Shipment ID Number | |
| HVALIMG | 256 characters | High Value Image Path | |
| HVALFMT | 6 characters | High Value Image Format | |
| FORMIMG | 256 characters | Intl. Form Image Path | |
| FORMFMT | 6 characters | Intl. Form Image Format | |
| CODIMG | 256 characters | COD Form Image Path | |
| CODFMT | 6 characters | COD FORM Image Format |
Table Structure - UPSSARSPK
| Name | Data Type | Description | Notes |
|---|---|---|---|
| PID | 15,0 packed | Parent Unique ID | |
| UID | 15,0 packed | Child Unique ID | |
| TRACKNBR | 21 characters | Package Tracking Number | |
| SVCCURCD | 3 characters | Service Options Currency Code | |
| SVCCHRG | 15,2 packed | Service Charge Cost | |
| LBLIMG | 256 characters | Label Image Path | |
| LBLFMT | 6 characters | Label Image Format | |
| HTML | 256 characters | HTML Path |
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 UPSSCRQ.
- Insert a record into UPSSCRQ.
- For each package, call UPS_getUID to get the UID that will be used to store and identify the record in UPSSCRQPK.
- Insert each package into UPSSCRQPK.
- Call UPS_shipConfirm, passing the UID used when writing to UPSSCRQ and the Krengel Ship for UPS Error Data Structure.
- The UPS_shipConfirm API will send the request to the UPS web service, and will store the response in UPSSCRS.
- 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 UPSSCRS.
- At this point, you have not created a shipment with UPS. The information in UPSSCRS should be reviewed, and then the UPS_shipAccept API should be called, passing the UID used when writing to UPSSCRQ and the Krengel Ship for UPS Error Data Structure. Calling the UPS_shipAccept API authorizes UPS to bill for the shipment.
- The UPS_shipAccept API will send the request to the UPS web service, and will store the response in UPSSARS and UPSSARSPK
- 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 UPSSARS and UPSSARSPK.