By Lance Robinson - Technical Evangelist, /n software.
Requirements: /n software FedEx Integrator

Introduction

FedEx Integrator is a toolkit that enables software developers to quickly and easily incorporate FedEx shipping capabilities into their software applications and websites.  The toolkit includes components for shipping, tracking, and rate calculation:

• Locator component: Used to locate FedEx locations that are close to a given address or telephone number.
• Rates component: Retrieves courtesy rate quotes from FedEx for a specific account and service types.
• Ship component: Generates FedEx shipping labels complete with address and barcodes. This component also gives you the ability to cancel a shipment or close out FedEx Ground shipments.
• Track component: Provides tracking information for packages.
• Subscribe component: Provides a unique meter number specific to the customer's FedEx account.

---

 

Getting Started

Certification with FedEx

FedEx requires that all applications that print shipping labels pass a series of certification tests prior to being placed in production. The full version of IBiz FedEx Integrator gives you access to a certification package that makes this process very easy. The certification package is available by request to all owners of any licensed version of the FedEx Integrator.  It includes all test scenarios required by FedEx for FedEx Express and Ground (international and domestic), and Home Delivery. Through the application included in the certification package you can generate all shipping labels for selected scenarios applicable to your shipping needs with a click of a button.  After you get registered for this certification you'll also need to subscribe to FedEx Services (next paragraph).

To request materials for certification please contact /n software support.

Subscribe to FedEx Services

Before you can communicate with FedEx electronically you need to have both a FedEx account number and a FedEx meter number.  First you must have a FedEx account number, then you can use the Subscribe component included in the FedEx Integrator to subscribe to FedEx Services and get a meter number assigned to your account number.  This subscription is a one-time process.

The response to the Subscribe component's Register method will contain your assigned FedEx Meter Number as well as which FedEx services are authorized for that particular FedEx Account.

You will need to submit this subscription request twice:

• Once after you are registered in the FedEx Test Environment. To register in the FedEx Ship Manager (FSM) Direct program, go to http://www.fedex.com/us/solutions/wis/.
• Once after you are certified to access the FedEx Production Environment.

You should record the returned meter number and use it with each request sent to FedEx.

Your typical online retailer needs to ship items to his customers, and this simple task involves several steps:

1. Allow the customer to choose what type of shipping to use, and show the cost and delivery time of each choice.
2. Print a shipping label for the package.
3. Provide the customer with a shipment tracking number.
4. Give the package to FedEx.

Now here is how we can implement each of these tasks.

1.   Allow the customer to choose what type of shipping to use, show them the cost and estimated delivery time of each choice.

After you get the customers shipping address, you can retrieve the cost of delivery and an estimated date of delivery using the Rates component.

To determine the rate to ship a regular FedEx envelope from my zip code (27502) to a sample address (20770), I can use the following code:

  Rates1.ServerURL = "https://gateway.fedex.com:443/GatewayDC";
  Rates1.AccountNumber = acctnum;
  Rates1.MeterNumber = meternum;
  Rates1.FromPostalCode = "27502";
  Rates1.FromState = "NC";
  Rates1.DestinationPostalCode = "20770";
  Rates1.DestinationState = "MD";
  Rates1.PackagingType = ptFedexEnvelope; //0
  Rates1.Weight = "1";
  Rates1.Value = "10.00"; //0
  Rates1.ServiceType = stUnspecified; //0, show all service type rates
  Rates1.GetRates();

Note that package weight is required for all packages, but it is only necessary to specify the dimensions of the package (length, width, and height - not shown in the example above) if you set the PackagingType to ptYourPackaging.  Note that ptYourPackaging is required for FedEx Ground services.

Rates depend on location (from and destination), dimensions and/or weight, packaging type (envelope, box, etc), carrier code, and service type.   Available service types are:

• Priority Overnight
• Standard Overnight
• First Overnight
• FedEx 2 Day
• FexEx Express Saver
• International Priority
• International Economy
• International First
• FedEx 1 Day Freight
• FedEx 2 Day Freight
• FedEx 3 Day Freight
• FedEx Ground
• Ground Home Delivery
• International Priority Freight
• International Economy Freight
• Europe First International Priority

The ServiceType property has an "unspecified" setting that will tell the component to retrieve rates for all available service types.  The CarrierCode property allows you to specify the carrier that will be used, either FDXE (FedEx Express, the default) or FDXG (FedEx Ground).

 

As you can see from the above screenshot of the Rates demo that comes with the FedEx Integrator .Net Edition, when the service type is unspecified, FedEx will return rate quotes for all applicable service types (overnight, 2 day, etc).   The delivery date, charges, discounts, and other details about the rate quotes are contained in a set of Service properties like ServiceDeliveryDate, ServiceDiscNetCharge, etc.

2.  Print a shipping label for the package.

Use the Ship components to generate a shipping label for your package.  The component will generate labels in PDF, PNG, or thermals Elton, Zebra, and UniMark.  Choose the label image type through the LabelImageType property.  The Ship component can generate labels for all service types.

  Ship1.AccountNumber = acctnum;  
  Ship1.MeterNumber = meternum;
  Ship1.ServerURL = "https://gatewaybeta.fedex.com:443/GatewayDC";
  Ship1.FromName = "John Smith";
  Ship1.FromAddress1 = "475 L'Enfant Plaza, SW";
  Ship1.FromCity = "Washington";
  Ship1.FromState = "DC";
  Ship1.FromPostalCode = "20260";
  Ship1.FromCountry = "US";

  Ship1.FromPhoneNumber = "1234567890";
  Ship1.ToName = "Jane Smith";
  Ship1.ToAddress1 = "8 Wildwood Drive";
  Ship1.ToCity = "Durham";
  Ship1.ToState = "NC";
  Ship1.ToPostalCode = "27712";
  Ship1.ToCountry = "US";
  Ship1.ToPhoneNumber = "1234567890";
  Ship1.Weight = 1;  //lbs
  Ship1.CarrierCode = "FDXE"; //FedEx Express
  Ship1.ServiceType = stStandardOvernight; //1, standard overnight
  Ship1.DropoffType = dtRegularPickup; //0, regular pickup
  Ship1.DropoffType = dtRegularPickup; //0, regular pickup
  Ship1.LabelImageType = ltPNG; //1, PNG file
  Ship1.ShippingLabelFile = "shippinglabel.png";
  Ship1.ShipPackage();

After the call to ShipPackage, you'll have a file called shippinglabel.png (depending on how you set the ShippingLabelFile and LabelImageType properties) that you can print, which looks something like the one pictured above.  Note that if you're using the test server, as in the example above, the label will always be the test label shown here ("TEST LABEL CONTACT", "TEST LABEL COMPANY", etc).  Affix this label to your package along with postage and it is ready to go. 

Also the DeliveryDate and DeliveryDay (day of week) properties will be populated with the reply from FedEx indicating when the package will be delivered.

The Ship component is extremely flexible and provides a wide variety of properties that can be set to effect the generated label itself.  For COD shipments, you can set the COD property to true and set the CODAmount and CODType with the details of the payment itself.

 

FedEx Express Carrier

All of the ServiceTypes except FedEx Ground and FedEx Ground Home Delivery are for FedEx Express services.

FedEx Express shipments are also eligible for FedEx Hold At Location services.  Use this option if you need your package to be held at a FedEx location instead of delivered to the final destination. This is useful if you need your package earlier than the scheduled delivery time, or if you won't be available to receive a delivery.  To turn on this option, set the HoldAtLocation property to true, and specify the location in the other HoldAt properties (HoldAtAddress, HoldAtCity, etc).  Locations can be searched for with the Locator component included in FedEx Integrator.

 

FedEx Ground Carrier

The service types available for FedEx Ground are FedEx Ground and FedEx Ground Home Delivery.

• End of Day Close
  
  If you're shipping through the FedEx Ground carrier (i.e., the CarrierCode property is set to "FDXG"), you should perform the FedEx Ground End of Day Close procedure at the end of every shipping day.  To perform this procedure, call the CloseOperation method.
  
  A printed Manifest report is required to be tendered along with your packages if they are being picked up by FedEx Ground. If you are dropping the packages off at a FedEx drop-off location, the manifest is not required.  After a call to the CloseOperation, the manifest report will be included in its unencoded form in the Manifest property, and also written to disk in the file specified by the ReportFile property. 
  
  The CloseOperation can also be used to generate reports instead - to use the operation for this functionality, just set the ReportOnly property to true and set the ReportIndicator property to the type of reports you'd like to generate.  Then calling CloseOperation will cause FedEx to return the specified report (in either the Manifest, MultiweightReport, HazMatCertificate, or CODReport properties, depending on the value of ReportIndicator) for the past 3 days of shipping data.
  
  A customer cannot cancel any shipments once they are closed out. However, shipments can be added to a day's shipment after a close operation has been performed and multiple closes can be performed in a day.
  
• FedEx Ground services also have the option of the FedEx Ground COLLECT service, explained in the Payment Options section below.
  

Shipping Payment Options

Payment options can be specified using the Ship component's Payor properties.  Specifically, the payment type is set with the PayorType property, which can take 1 of 4 possible values:

• Sender - The default, using this option means that the account identified by the AccountNumber property will be billed for the shipping charges.
• Recipient - The recipient of the package will be billed for the shipping charges.  To ship this way, you'll need to know the recipients account number and specify it in the PayorAccountNumber property, along with the PayorCountry.
• Third Party - A third party will be billed for the shipping charges.  To ship this way, you'll need to know an account number and specify it in the PayorAccountNumber property, along with the PayorCountry.
• FedEx Ground COLLECT - For FedEx Ground only, this service gives you the ability to be invoiced for incoming shipments, as opposed to paying the suppliers shipping charges.  To use this service, set the PayorType property to 3 (COLLECT).  Shipping charges will be billed to the account identified by the AccountNumber property.

COD - Collect On Delivery

In order to ship COD (collect on delivery) packages, use the COD properties.  With COD, the recipient is paying for the product being shipped rather than the shipping itself.  To do this, first set the COD property to true, then set the CODType and CODAmount.  CODType can be CASH, GUARANTEED FUNDS (certified check, money order or cashier's check) or ANY (any of the previous plus company or personal checks).

Signature Options

Signature options can be specified in the Ship component by setting the SignatureOption property.  The property has 4 possible values:

• No Signature - Only available for FedEx Express shipments that are not alcohol, hold at location, dangerous goods, and  have a declared value less than $500.
• Indirect - A signature will be obtained from someone at the delivery address, a neighbor, or a door tag. 
• Direct - A signature will be obtained from someone at the delivery address.
• Adult - A signature will be obtained from someone at the delivery address who has a government issued photo id proving that they are at least 21 years of age.

 

International Shipments

For international shipments, FedEx Express requires a Commercial Invoice document (which you must print yourself).  The Ship component has a set of Commodity properties such as CommodityCount, CommodityDescription, CommodityWeight, etc.  You'll need to use these properties to build your ship request if you are shipping internationally, and FedEx will automatically forward this commodity information to customs.  Speaking of customs, you'll also need to set the TotalCustomsValue property to the total value of the shipment, including freight, insurance, and other charges.

Also required for dutiable shipment is the DutiesPayorType property.  This property should be set to indicate who will be paying the duty for the shipment - the sender, the recipient, or a third party.

3.  Provide the customer with a shipment tracking number.

The Ship component that you use in step 3 will provide you with a tracking number automatically.  The component has a TrackingNumber property where this information is provided after the call to ShipPackage returns.

With this tracking number you can use the Track component of the FedEx Integrator to retrieve information about the status of the shipment.  Certainly as far as the customer is concerned, they can just be directed to visit the FedEx website and do their shipment tracking there.  But the Track component would be particularly useful to the merchant for automatically confirming delivery of all packages sent.  Here is an example:

  //test server
  Track1.ServerURL = "http://testing.shippingapis.com/ShippingAPITest.dll";
  Track1.DetailScans = true;  
  Track1.TrackByTrackingNumber("<insert tracking number>");

4.  Give the Package to FedEx.

Now that the order process is complete, its time (hopefully) to actually ship the product to the customer.  The procedure for getting your package into the hands of FedEx depends on the value of the DropoffType property when you created the shipping label with the Ship component.  Possible options are:

• Regular Pickup - The shipper already has an every-day pickup scheduled with a courier.
• Request Courier - The shipper will call FedEx to ask for a courier.
• Drop Box - The shipper will drop the package in a FedEx drop box.
• Business Service Center - The shipper will drop off the package at an authorized FedEx business service center.
• Station  - The shipper will drop off the package at a FedEx Station.

You can use the Locator component to search for FedEx Stations and FedEx authorized service centers in close proximity to your location.  All done, happy shipping!

Conclusions

This article demonstrates the ease of use of the /n software FedEx Integrator.  In this tutorial I've gone over some of the most commonly used components and uses, however if there are any questions you have that I've not covered here please do not hesitate to contact me via the link at the top or bottom of this page.

Notes:

• AccountNumber and MeterNumber properties are required for all FedEx transactions.
• The test server URL for all requests is "https://gatewaybeta.fedex.com:443/GatewayDC".
• The live production URL will be provided to you by FedEx after your application has been approved/certified by FedEx Web Integration Solutions team.

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.