Materials:
Contents
- Introduction
- Purchasing Postage
- Rating Packages
- Generating a Label
- Tracking Packages
- Getting Support
Introduction
To work with Endicia use the USPS components. Whenever working with Endicia the PostageProvider property should be set to ppEndicia. During the development phase there is a testing environment provided. Any of the USPS components can be easily configured to make requests to the testing environment while using a built-in sandbox account. To configure the component for testing set the EndiciaTestMode configuration setting to 1, like this example:
Uspsship ship = new Uspsship();
ship.PostageProvider = UspsshipPostageProviders.ppEndicia;
ship.Config("EndiciaTestMode=1");
When ready to move to production please sign up for a production account here: https://account.endicia.com/?referredBy=lsft.
To configure the component for production set USPSAccount.AccountNumber and USPSAccount.Password to a production account. There is no need to set USPSAccount.Server, it will be set automatically.
Uspsship ship = new Uspsship();
ship.PostageProvider = UspsshipPostageProviders.ppEndicia;
ship.USPSAccount.AccountNumber = "Production AccountNumber";
ship.USPSAccount.Password = "Production Password";
Purchasing Postage
An Endicia account has a postage balance that can be used to purchase postage. Postage is used any time a label is generated.
The Uspsmgr component is used to purchase postage and manage accounts. To get information about an account call the GetAccountStatus method, like this example:
Uspsmgr mgr = new Uspsmgr();
// Postage provider is exposed
// as a config with Uspsmgr.
mgr.Config("PostageProvider=1");
mgr.Config("EndiciaTestMode=1");
mgr.GetAccountStatus();
Console.WriteLine("Available Postage: " + mgr.PostageBalance + "\r\n"
+ "Is the account active? " + (mgr.Config("AccountStatus") == "A" ? "Yes." : "No.") + "\r\n"
+ "Ascending Balance: " + mgr.Config("AscendingBalance"));
The primary piece of account information that comes back is PostageBalance, which is the available postage balance in the account. Purchasing postage is done with the Recredit method, like this example:
mgr.Recredit("100.00");
Rating Packages
Once there is postage available to an account the next step would be to estimate a rate for shipping a package. Rates returned from Endicia’s server are estimates and may not reflect the final price of sending a package. If there are any questions or disputes about the final price charged for shipping a package please get in touch with Endicia directly.
Uspsrates is used to rate packages and there are two ways to rate a package. The first is without selecting a specific service type. This will return a list of available services along with their rates. Here is an example:
Uspsrates rates = new Uspsrates();
rates.PostageProvider = UspsratesPostageProviders.ppEndicia;
rates.Config("EndiciaTestMode=1");
rates.Packages.Add(new PackageDetail());
rates.Packages[0].Weight = "1.1";
rates.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging;
rates.SenderAddress.ZipCode = "27516";
rates.RecipientAddress.ZipCode = "28608";
rates.GetRates();
foreach (ServiceDetail service in rates.Services)
{
Console.WriteLine(service.ServiceTypeDescription
+ " would cost $"
+ service.ListNetCharge);
}
The second way to rate shipping a package is to provide a specific service type to the RequestedService property before calling GetRates. Building on the last example:
rates.RequestedService = ServiceTypes.stUSPSPriority;
rates.GetRates();
ServiceDetail service = rates.Services[0];
Console.WriteLine(service.ServiceTypeDescription
+ " would cost $"
+ service.ListNetCharge);
When requesting a specific service there will be just one returned entries in the Services collection. This will be for the requested service.
Typically the more information provided about a package the more accurate the estimated rate will be. For simplicity’s sake these examples used a bare minimum of information.
Generating a Label
After getting an estimated rate for shipping a package a label will need to be generated and affixed to the packaging. Domestically shipped packages (those shipped only within the borders of the United States) will have their labels generated with the Uspsship component while all others will use the Uspsshipintl component.
To create a label Endicia will need to know some information about how the package should be shipped, including:
- Who is sending the package.
- Who is receiving the package.
- What service will be used.
- Basic package information like weight and packaging type.
All of this information can be set with properties and/or configuration settings. Here is an example:
Uspsship ship = new Uspsship();
ship.PostageProvider = UspsshipPostageProviders.ppEndicia;
ship.Config("EndiciaTestMode=1");
ship.LabelImageType = UspsshipLabelImageTypes.sitJPG;
ship.ServiceType = ServiceTypes.stUSPSFirstClass;
ship.TransactionId = "54321";
ship.SenderContact.FirstName = "Alice";
ship.SenderContact.LastName = "Wonderland";
ship.SenderAddress.Address1 = "101 Europa Dr.";
ship.SenderAddress.Address2 = "Suite 110.";
ship.SenderAddress.City = "Chapel Hill";
ship.SenderAddress.State = "NC";
ship.SenderAddress.ZipCode = "27517";
ship.RecipientContact.FirstName = "Bob";
ship.RecipientContact.LastName = "Belcher";
ship.RecipientAddress.Address1 = "Lands End Trail";
ship.RecipientAddress.City = "San Francisco";
ship.RecipientAddress.State = "CA";
ship.RecipientAddress.ZipCode = "94121";
ship.Packages.Add(new PackageDetail());
ship.Packages[0].Weight = "1.0";
ship.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging;
ship.Packages[0].ShippingLabelFile = @"C:\labels\order12345.jpg";
ship.GetPackageLabel();
Console.WriteLine("Track this package using this number: " + ship.Packages[0].TrackingNumber);
If the call is successful then a label will be returned and saved to the location specified with ShippingLabelFile. Alternatively the label data can be worked with by querying the ShippingLabel property. A tracking number will also be returned and is available in the TrackingNumber property.
A package can be dropped off or alternatively a pickup can be scheduled. To schedule a pickup with Endicia use the SchedulePickup method, like in this example:
Uspsship ship = new Uspsship();
ship.PostageProvider = UspsshipPostageProviders.ppEndicia;
ship.Config("EndiciaTestMode=1");
// This needs to be set to a different server when scheduling a pickup.
ship.USPSAccount.Server = "https://elstestserver.endicia.com/ELS/ELSServices.cfc";
ship.SenderContact.FirstName = "Rick";
ship.SenderContact.LastName = "Sanchez";
ship.SenderContact.Company = "n software";
ship.SenderAddress.Address1 = "101 Europa Dr.";
ship.SenderAddress.Address2 = "Suite 110";
ship.SenderAddress.City = "Chapel Hill";
ship.SenderAddress.State = "NC";
ship.SenderAddress.ZipCode = "27517-2379";
ship.SenderContact.Phone = "(919) 544-7070";
ship.Config("SenderPhoneExt=4"); // For technical support.
ship.CountExpress = 1;
ship.CountInternational = 1;
ship.CountOther = 1;
ship.CountPriority = 1;
ship.TotalWeight = 14;
ship.PackageLocation = UspsshipPackageLocations.plOther;
ship.Config("SpecialInstructions=Packages are behind the screen door.");
ship.Config("TESTMODE=true");
ship.SchedulePickup();
Console.WriteLine("The package will be picked up on " + ship.ShipDate);
When scheduling pickups the number of Priority or Express packages must be provided through the CountPriority or CountExpress properties. Additionally the TotalWeight of all packages must be provided. The address that the package(s) will be picked up from is set with SenderAddress. If the PackageLocation is plOther then SpecialInstructions also needs to be provided. Otherwise any special instructions are optional.
Tracking Packages
Once a package is in possession of USPS it can be tracked with the Uspstrack component. Tracking is fairly simple, just call the TrackShipment method and pass in a tracking number. When the response comes back from the server the method will return and any tracking events will be contained in the TrackEvents collections. Here is an example:
Uspstrack track = new Uspstrack();
track.PostageProvider = UspstrackPostageProviders.ppEndicia;
track.Config("EndiciaTestMode=1");
track.Config("RequestId=12345"); // Endicia requires that a RequestId is provided.
track.TrackShipment("EJ958083578US");
foreach (TrackDetail trackEvent in track.TrackEvents)
{
Console.WriteLine("----Event----\r\n"
+ trackEvent.Status
+ trackEvent.Date + " - " + trackEvent.Time
+ trackEvent.City + ", " + trackEvent.State + trackEvent.ZipCode + "\r\n");
}
Shipping packages can be complicated, but we sincerely hope that 4D Shipping makes it significantly easier for you. There is more to be discovered when working with this product, like international shipping, but hopefully this is plenty to get started with. If you need any assistance while working with 4D Shipping please check out the support options below.
Getting Support
If you are stuck with 4D Shipping there are options for help. Please have a look through the Knowledge Base and Documentation first, as often many common questions can be answered there. If you are still having trouble, please contact our support team and they would be happy to help you.
- Documentation: http://cdn.4dpayments.com/DXF/cs/
- KnowledgeBase: https://4dpayments.com/kb/#dshipping
- Support: support@4dpayments.com