Introduction

Welcome to 4D Shipping SDK, the most comprehensive suite of components for shipping, tracking, label creation, rate calculation, and address verification! The included components allow for easy integration with shipping services of major international carriers including FedEx, UPS, USPS, and Canada Post.

Once the components are integrated into your application, you can communicate with the servers over a secure SSL connection.

Before using these components, the user must contact the specified provider to obtain access to that provider's OnLine Tools.

Each request requires specific processing based on the type; therefore, each component has a unique URL for connection purposes.

Note: FedEx and the FedEx logo are registered service marks. All rights reserved.

Note: UPS, the UPS Shield trademark, the UPS Ready mark, the UPS OnLine Tools mark and the Color Brown are trademarks of United Parcel Service of America, Inc. All Rights Reserved.

Note: United States Postal Service, Postal Service, Post Office, StampsOnline, Express Mail, Priority Mail, Delivery Confirmation, First-Class Mail, Global Priority Mail, Parcel Post, Global Express Guaranteed, ZIP Code, the Eagle Logo and Fly Like An Eagle are trademarks of the United States Postal Service. This list is not intended to be exhaustive. For a more complete listing of many USPS trademarks, visit the U.S. Patent and Trademark Office Web site at the link below. http://www.usps.com/homearea/docs/termsofuse.htm?from=home_footer&page=termsofuse

Note: Endicia, A Newell Rubbermaid Company. All rights reserved.

Note: Certain Canada Post trademarks, trade-names, images, logos and pictures are proprietary to Canada Post Corporation or other entities. All rights reserved.

Included Components

CanadaPostAddress	Easily find nearby Canada Post locations.
CanadaPostRates	Provides access to pre-ship rate information for a single package per your established Canada Post account rates.
CanadaPostShip	Allows you to generate domestic labels using Canada Post.
CanadaPostShipIntl	Allows you to generate international labels using Canada Post.
CanadaPostTrack	Provides tracking information and SPOD for a given tracking number or other shipment identifier.
CertMgr	The CertMgr component is used to create, read, and manage certificates.
EzAddress	Checks U.S. shipping addresses.
EzRates	Provides domestic or international rates based on weight, service, and origin/destination information.
EzShip	Allows you to generate a shipping label for any domestic services complete with addresses and barcode.
EzTrack	Retrieves tracking data for any package shipped from origin to delivery.
FedExAddress	Allows you to validate or complete recipient addresses.
FedExFreightRates	Provides access to pre-ship rate information for a freight shipment per your established FedEx account rates.
FedExFreightShip	Allows you to generate a FedEx shipping label for any of FedEx freight services complete with addresses and barcode, or cancel a shipment.
FedExMgr	Provides a way to subscribe a provider with FedEx Web Services and to register a CSP user with FedEx.
FedExRates	Provides access to pre-ship rate information for a single package per your established FedEx account rates.
FedExShip	Allows you to generate a FedEx shipping label for any of FedEx domestic services complete with addresses and barcode, cancel a shipment or close out the FedEx Ground shipments.
FedExShipIntl	Allows you to generate a FedEx shipping label for any of FedEx international services complete with addresses and barcode, cancel a shipment, or close out the FedEx Ground shipments.
FedExTrack	Provides tracking information, SPOD, and notification for a given tracking number or other shipment identifier.
OAuth	The OAuth component is used to authorize a client and provide an authorization string used in future requests.
ShipRequest	Allows you to create, send, and parse a custom request.
UPSAddress	Checks either a general validation of a city, state, and zip code, or a validation and classification of a specific, street-level address, and suggests alternates if an error is discovered.
UPSFreightRates	Provides UPS Freight Rates service.
UPSFreightShip	Provides UPS Freight Shipment service.
UPSRates	Provides domestic or international rates based on weight, service, and origin/destination information.
UPSShip	Allows you to generate a UPS shipping label for any of UPS domestic services complete with addresses and barcode, or cancel shipments.
UPSShipIntl	Allows you to generate a UPS shipping label for any of UPS international services complete with addresses and barcode, cancel shipments.
UPSTrack	Provides up-to-the-minute status reports of shipments, domestic and international, from origin to delivery.
USPSAddress	Provides address standardization, zip code lookup and city/state lookup.
USPSMgr	Provides a way to perform account management operations.
USPSRates	Determines domestic and international postage rates based on weight, size, class of mail, and origin/destination information.
USPSShip	Allows you to generate a USPS shipping label for any of USPS domestic services complete with addresses and barcode, or manage pickups. To get a label with USPS, postage must be paid. To get a label with postage you must use ppNone , ppEndicia , or ppStamps as your PostageProvider . Note that when PostageProvider is set to ppNone the GetPackageLabel method will generate an eVS label. The eVS (or Electronic Verification System) Label API allows high-volume package mailers and package consolidators to document and pay postage, including special service fees, using electronic manifest files.
USPSShipIntl	Allows you to generate a USPS shipping label for any of USPS international services complete with addresses and barcode. Note that when PostageProvider is set to ppNone the GetPackageLabel method will generate an eVS label. The eVS International Label API lets customers generate eVS labels with integrated customs declaration forms.
USPSTrack	Retrieves tracking data for any package shipped with Delivery or Signature confirmation.

Additional Information

You will always find the latest information about 4D Shipping SDK at our web site: www.4dpayments.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@4dpayments.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@4dpayments.com.

Thank You!

Thank you for choosing 4D Shipping SDK for your development needs. We realize that you have a choice among development tools, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Getting Started

This section provides step-by-step instructions for creating and configuring accounts needed for the different shipping providers.

FedEx

Before starting to use FedEx components, you must first register for these services with FedEx by visiting Developer Portal at https://developer.fedex.com/api/en-us/home.html and following the instructions.

FedEx Developer Portal administrators must associate FedEx accounts to their organization in order to run their transactions. If you don't already have an organization, you will need to first create an organization and then associate your account(s) to your organization.

Next step is to create an API project to obtain the Client Id (API Key) and Client Secret (Secret Key), which are used to obtain the bearer token through OAuth. The bearer token is then used to authenticate with FedEx when requesting rates, labels etc.

The "Getting Started" guide https://developer.fedex.com/api/en-us/get-started.html provides detailed instructions. The relevant tabs are "Create organization" and "Create API project".

Once the components are integrated, your server communicates with the FedEx server over a secure SSL connection.

Before moving to the production environment, you will have to go through the certification process with FedEx for the Ship services only (which is considered an advanced service by FedEx).

You do not need to go through the certificate process to use the standard services (Rates, Track, Locator). However, when using these services in the production environment, you will have to use the production credentials in all your requests.

Our components ensure a smooth transition during this process. It ensures that your implementation meets a number of requirements for safe, secure, and effective operation of your solution in the FedEx production environment.

The full version of the toolkit gives you access to a certification package that makes this process very easy. The certification package is available by request. 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.

IMPORTANT: When creating the API project make sure to select all the APIs that you intend to use, otherwise, if you make a call to an API that you have not selected you may see an authentication error even though your credentials are good.

IMPORTANT: By default the components are configured to send request to the production environment. In order to send request to the test environment you must set the TESTMODE config to true like component.Config("TESTMODE=true"); The component automatically determines the correct end point - you do not need to set the component.UPSAccount.Server

UPS

The UPS components allow you access to the UPS on-line services, providing easy access to address validation, tracking, shipping, rates, time in transit, and pickup APIs.

Once the components are integrated into your application, you can communicate with the UPS server over a secure SSL connection.

Before using these components, the user must contact UPS to obtain access to UPS OnLine Tools. For this, please visit https://developer.ups.com/get-started?loc=en_US.

To begin your integration, you will need the following to sign into the UPS Developer Portal and obtain API credentials:

• UPS username - if you do not already have one you can create it at https://wwwapps.ups.com/doapp/signup?loc=en_US.
• UPS shipper account (six digit number) that is linked to your UPS ID.

Next, you'll need to obtain your OAuth Credentials.

Once you have a UPS username and a shipper account, you can obtain your credentials by creating an application on the UPS portal. During this process you will link your shipper account and email address to the application you create and obtain your Client ID and Client Secret.

Note: The UPS username used to sign-in when creating the credentials will be explicitly tied to the OAuth credentials. Only shipper accounts associated to that username will be valid when used in API requests such as Ship and Rate.

Once you have obtained the Client ID and Client Secret you can then use the OAuth component to obtain an access token, which is passed as a bearer token in the request and serves to authorize that request.

IMPORTANT: When creating the API project make sure to select all the APIs that you intend to use, otherwise, if you make a call to an API that you have not selected you may see an authentication error even though your credentials are good.

IMPORTANT: By default the components are configured to send request to the production environment. In order to send request to the test environment you must set the TESTMODE config to true like component.Config("TESTMODE=true"); The component automatically determines the correct end point - you do not need to set the component.UPSAccount.Server

Each request requires specific processing based on the type; therefore, each component has a unique URL for connection purposes.

The following URLs may be used for testing:

USPS

The USPS components allow you access to the on-line services of the United States Postal Service (USPS). These provide easy access to shipping and tracking information.

Once the components are integrated, your server communicates through the USPS server over HTTP using XML.

Before using these components, the user must contact USPS to obtain credentials necessary to use USPS's online tools. To gain these credentials, please visit https://secure.shippingapis.com/registration/. Also, more information regarding USPS's online tools can be found here: https://www.usps.com/business/web-tools-apis/welcome.htm.

Endicia

When using the Endicia postage provider for the USPS components, you do not need credentials to test as Endicia's test servers do not check the credentials that you pass. You will however need to certify your labels with Endicia before getting production access. More information regarding Endicia can be found at http://www.endicia.com/Developers/LabelServer/.

To sign up for an account visit http://www.endicia.com/developer-resources/endicia-label-server-apis.

Canada Post

The Canada Post components allow you to access the on-line services of Canada Post. these provide easy access to rating, shipping, and tracking information.

Once you have integrated with the components, your server communicates directly with the Canada Post servers over HTTP using XML.

Before using the components, the user must contact Canada Post to obtain the necessary credentials to use Canada Post's APIs. To gain these credentials, please got to https://www.canadapost.ca/cpotools/apps/developers/home and click the Join button near the top of the page.