Opentaps Shipping Setup

opentaps can access the web API's for UPS, US Postal Service, DHL, and Federal Express. To use opentaps with these shipping services, contact your representative and obtain the necessary shipping credentials. Then edit the file applications/product/config/shipment.properties and modify them as needed.

IMPORTANT NOTE: For external shipping rate estimates services to work properly, you must configure warehouses with the correct ZIP code.

Setting up US Postal Service

You can register for an shipping API key on the USPS Web Site. There you can also apply for permission to use the Address Validation API on the USPS API Request Page, so that you can set up opentaps for address validation.

USPS may ask you to test your service. If so, see USPS Rate Calculator Setup for their specific instructions on how test it. Note that the USPS testing URL can only accept certain pre-set zip code and weight combinations. The only production URL which seems to work with RateV2Request is http://production.shippingapis.com/ShippingAPI.dll Finally, USPS service classes other than “Parcel” require a container type to be specified for rate estimation.

Once you have the production API keys, you will need to modify the file applications/product/config/shipment.properties to set the USPS webtools key and the production access URL.

When trying to get USPS rate estimates, make sure that you do not pass a <Container> tag in your string if you are requesting a rate for the Express and the Priority. Otherwise, you will get error messages like: "Invalid container type. Valid container types for Priority Mail are Flat Rate Envelope and Flat Rate Box." or "Valid container type for Express Mail is Flat Rate Envelope." See USPS Rate Estimate API.

Setting up UPS Shipping

You will need your UPS account number, license key number, and user ID and password. Edit the file application/products/config/shipment.properties and put those attributes there.

If you want to schedule shipments with UPS, ou must be approved to use the Premium Shipping Tools from UPS. Otherwise, you will not be able to generate labels with opentaps. If when trying to schedule a shipment with UPS in opentaps you see the error:

 An error occurred [code:250003] with severity Hard: Invalid Access License number.

then your shipping credentials have not yet been approved for online shipping.

If you need to send XML samples to UPS for certification, you can configure opentaps to save your UPS XML for you. The path is configured in application/product/config/shipment.properties under shipment.ups.save.certification.info and shipment.ups.save.certification.path

=Cash On Delivery (COD)

A UPS shipment can be set up as COD if the only payment method for the order of the shipment is COD, and you have enabled COD in application/products/config/shipment.properties by setting the shipment.ups.cod flags. The COD amount will be the value of the order plus the COD surcharge you have configured. When you receive a check for all your COD shipments, you can use the Receive COD Shipment Screen.

Insurance

If you need to insure your your shipments, you can configure it in hot-deploy/warehouse/config/warehouse.properties When your shipment is packed, it would check each package of the shipment, add up the value of all the order items in that package, and check that value against the configured minimum insured package value from warehouse.properties If this value exceeds the minimum, it will set the shipment package's insured value fields to the value of that package. Later, when your package is actually scheduled with UPS, if there is an insured value for your package, it will add the insured value to the UPS shipment XML.

If you do not have actual weights defined for your products, the UPS rate estimate routine will not generate the right XML, and you may get this error:

<Error>
<ErrorSeverity>Hard</ErrorSeverity><ErrorCode>10002</ErrorCode>
<ErrorDescription>The XML document is well formed but the document is not valid</ErrorDescription>
<ErrorLocation>
<ErrorLocationElementName>RatingServiceSelectionRequest/Shipment/Package</ErrorLocationElementName>
</ErrorLocation>
</Error>

In particular, shipping package weights may have to be integer values.

Setting up Federal Express

To use opentaps with FedEx, you would first need to register for a meter number by calling the fedexSubscriptionRequest request with a contact person name and the partyId of your company. Then, edit the file applications/product/config/shipment.properties and put in the meter number and your account number. You should now be able to create shipments with FedEx and schedule them on the FedEx test server. Note that the FedEx test server will return a label with test addresses for express service but real addresses for ground service.

Once you're satisfied, change the FedEx URL setting in applications/product/config/shipment.properties to the production URL, and you should be able to schedule real shipments with FedEx.

If you plan to use FedEx to get rate estimates, you also need to configure the drop off and package types in shipment.properties.

Setting up DHL

DHL is handled with DHL ShipIT and is only available for US domestic shipments.. You will need to register with DHL and obtain a userid, password, and a shipping key. You will also need to set your DHL 9-digit account number. Finally, you must specify the format of the label image (GIF or PNG). For compatibility with XSL:FO, we recommend that you use PNG. There is a dhlRegisterAccount service which can help you register your account and obtain a shipping key from DHL.

Setting up Live Rate Estimates

To set up live rate estimates for your shipping methods, update the ProductStoreShipmentMeth entity and fill in the value of the serviceName field with the following services:

* UPS - upsRateEstimate
* FedEx - opentaps.fedexRateRequest
* DHL - dhlRateEstimate
* USPS - uspsRateInquire

This could be most easily done with a SQL query:

UPDATE PRODUCT_STORE_SHIPMENT_METH SET SERVICE_NAME='upsRateEstimate' WHERE PARTY_ID = 'UPS'

IMPORTANT WARNING - Live rate estimates depend on the availability of the carrier's web servers, which may be slow or unavailable at times. If this were to happen, your users might see "Rate Not Available" or a 0 or -1 for the shipping estimate, and they will be able to create an order with no shipping charges. You would have to later modify the order and manually enter a shipping charge.