Implementing the IShippingAdapter Interface

The shipping adapter can be used to integrate external applications or services that provide shipment processing functionality for a carrier. This adapter has methods available for rating, shipping, printing, voiding, and managing end of day activities such as closing manifests and transmitting package level data if applicable.

Overview

Every shipping adapter will have a main Ship() method that has an incoming ShipmentRequest object containing all of the shipment level and package level information needed to process the shipment. This method is where the developer would implement the following steps:

Convert the incoming ShipExec ShipmentRequest data to the required external format
Establish a connection to the external service or application
Process the shipment using the external service and receive the response data or capture any error messages
Convert the returned response or error data into a ShipExec ShipmentResponse object so that it can be passed back to the ShipExec Application

The ShipmentRequest and ShipmentResponse objects contain the following elements:

Package Defaults

Contains all of the shipment-level details as well as the default package attributes to be used across all packages unless the attribute value is set at the package level

Packages

A list of one or more packages that contain all of the unique individual package-level attributes for the shipment

Interface Members

Click here for a list of all members of the IShippingAdapter interface.

Sample Implementation of IShippingAdapter

Below is a sample implementation of IShippingAdapter

Note
All Adapters must have this configuration interface implemented in order for the adapter to function. See IAdapterConfigurationProvider for a sample implementation of IAdapterConfigurationProvider.

Copy

using System;
using System.Collections.Generic;
using System.Linq;
using MockShippingAdapter.Properties;
using PSI.Sox;
using PSI.Sox.Adapter;
using PSI.Sox.Adapter.Interfaces;
using PSI.Sox.Interfaces;

namespace MockShippingAdapter
{
    public class Shipping : IShippingAdapter
    {
        #region variables

        private string _adapterName = "PSIShipping";

        #endregion


        #region Properties


        public string AdapterSymbol
        {
            get { return "PSI.Mock"; }
        }

        public Version AdapterVersion
        {
            get { return new Version("2.3.10.11"); }
        }

        public Guid AdapterId
        {
            get { return new Guid("4C6D2B7E-3F11-45FD-A27D-C74C78XXXXA"); }
        }

        public string CompanyName
        {
            get { return "Shipping Services Inc"; }
        }

        public IAdapterConfiguration AdapterConfiguration { get; set; }

        public ILogger Logger { get; set; }

        public IProxySettings ProxySettings { get; set; }

        #endregion

        #region closeout

        public List<ManifestItem> GetManifestItems(string carrier, string shipper)
        {
            throw new NotImplementedException();
        }


        public List<CloseManifestResult> CloseManifest(string sc, string shipper, List<ManifestItem> manifestItems)
        {
            throw new NotImplementedException();
        }

        #endregion

        #region History

        public void DeleteHistoryItems(string sc, string shipper, List<HistoryItem> historyItem)
        {
            throw new NotImplementedException();
        }

        public List<HistoryItem> GetHistoryItems(string sc, string shipper)
        {
            throw new NotImplementedException();
        }

        public List<Package> GetHistoryPackageList(int historyItem, string sc, string shipper, bool minimalData = true)
        {
            throw new NotImplementedException();
        }

        #endregion

        #region print

        public AdapterPrintResponse PrintContainerDocument(string containerCode, string shipper, DocumentFormat documentFormat,
            PrinterDefinition printerDefinition)
        {
            throw new NotImplementedException();
        }

        public AdapterPrintResponse PrintDocument(long msn, string shipper, DocumentFormat documentFormat, PrinterDefinition printerDefinition)
        {
            var packageDocuments = AdapterDataHelper.GetPackageDocument(msn, null);

            var apr = new AdapterPrintResponse();

            apr.LabelData.AddRange(packageDocuments);

            var bundleId = AdapterDataHelper.GetBundleIdFromMsn(msn);
            var bundleDocuments = AdapterDataHelper.GetBundleDocument(bundleId, null);

            apr.DocumentData.AddRange(bundleDocuments);

            return apr;
        }

        public AdapterPrintResponse PrintManifestDocument(long historyItemId, string shipper, DocumentFormat documentFormat, PrinterDefinition printerDefinition)
        {
            throw new NotImplementedException();
        }


        #endregion

        #region ship, rate

        public List<ShipmentResponse> Rate(ShipmentRequest request, List<string> services, SortType sortType)
        {
            throw new NotImplementedException();
        }

        public ShipmentResponse Ship(ShipmentRequest request, bool shipWithoutTransaction)
        {

            var shipResp = new ShipmentResponse
            {
                PackageDefaults = new Package()
                {
                    BaseCharge = new Money
                    {
                        Amount = 10,
                        Currency = "USD"
                    },
                    FuelSurcharge = new Money
                    {
                        Amount = 1,
                        Currency = "USD"
                    },
                    Special = new Money
                    {
                        Amount = 1,
                        Currency = "USD"
                    },
                    Total = new Money
                    {
                        Amount = 11,
                        Currency = "USD"
                    },
                }
            };


            shipResp.PackageDefaults.Service = request.PackageDefaults.Service;

            var p = new PackageResponse
            {
                Msn = AdapterDataHelper.GetNextMsn(),
                BundleId = AdapterDataHelper.GetNextBundleId(),
                TrackingNumber = getTracking(),
                TrackingNumber2 = getTracking2(),
                ApportionedBase = new Money
                {
                    Amount = 10,
                    Currency = "USD"
                },
                FuelSurcharge = new Money
                {
                    Amount = 1,
                    Currency = "USD"
                },
                ApportionedSpecial = new Money
                {
                    Amount = 1,
                    Currency = "USD"
                },
                ApportionedTotal = new Money
                {
                    Amount = 11,
                    Currency = "USD"
                }
            };

            shipResp.Packages.Add(p);

            var pdoc = Resources.pdoc;
            var zpl = Resources.zpl;

            var documentData = new DocumentData();
            documentData.Pdoc = pdoc;
            documentData.RawData = zpl;
            documentData.RawFormat = RawFormat.Zpl;
            AdapterDataHelper.InsertPackageDocument(shipResp.Packages.First().Msn, documentData);

            return shipResp;
        }

        public ModifyPackageListResult ModifyPackageList(string carrier, List<long> msnlist, Package package)
        {
            return new ModifyPackageListResult() { ErrorCode = 1001, ErrorMessage = "Adapter does not implement modify package list fuctionality" };
        }

        public ReProcessResult ReProcess(string carrier, List<long> msnlist)
        {
            return new ReProcessResult() { ErrorCode = 1001, ErrorMessage = "Adapter does not implement reprocess functionality" };
        }

        #endregion

        #region search

        public Package Search(int msn, string sc, int searchCloseOutMode)
        {
            return new Package();
        }

        public List<Package> SearchByBundleId(int bundleID, string sc, int searchCloseOutMode)
        {
            throw new NotImplementedException();
        }

        #endregion

        #region void

        public Package VoidPackage(long msn, string carrier)
        {
             return new Package { ErrorCode = 0, ErrorMessage = "Package successfully voided" };
        }

        public List<TransmitItem> GetTransmitItems(string carrier, string shipper)
        {
            throw new NotImplementedException();
        }

        public void DeleteTransmitItems(string carrier, string shipper, List<TransmitItem> transmitItems)
        {
            throw new NotImplementedException();
        }

        public List<TransmitItemResult> TransmitItems(string carrier, string shipper, List<TransmitItem> transmitItems)
        {
            throw new NotImplementedException();
        }

        #endregion

        #region private

        private string getTracking()
        {
            return "34534";
        }

        private string getTracking2()
        {
            return "54324";
        }

        #endregion

        #region Adapter Specific values

        public List<DocumentFormat> GetDocuments()
        {
            return null;
        }

        public List<PackageType> GetPackageTypes()
        {
            return null;
        }

        public List<PaymentTerm> GetPaymentTerms()
        {
            return null;
        }

        public List<Carrier> GetCarriers()
        {
            return null;  }
        }

        public List<Service> GetServices()
        {
            return null;  }
        }
        public List<Carrier> GetCarriersbyShippers(List<string> shippers)
        {
            throw new NotImplementedException();
        }


        public IAdapterDataHelper AdapterDataHelper { get; set; }

        public string AdapterName
        {
            get { return _adapterName; }
        }

        public List<AdapterShipper> GetShippers()
        {
            return null;
        }


        #endregion

        public void Dispose()
        {

        }

        public void Init()
        {

        }
    }
}

Processing Rules

Criteria for Bundling Shipments

There are certain data fields that are required to be identical across all shipments in order for them to be bundled / grouped together. Below is a list of the fields that are evaluated when multiple shipments are bundled:

Aes Transaction Number
Carbon Neutral
Cod Amount
Cod Return Address
Cod Return Method
Cod Return Tracking Number
Comments
Commercial Invoice Method
Consignee
Consignee Account
Consignee Code
Consignee Email
Consignee Third Party Billing
Consignee Third Party Billing Account
Consolidation Id
Declared Value Amount
Declared Value Customs
Delivery Exception Notification Email
Delivery Notification Email
Direct Delivery
Documentation Consignee
Documents Only
Dropoff Appointment Number
Dry Ice Weight
Eei Notification Email
Eei Notification Sender Name
Export Declaration Statement
Export Reason
Exporter
Goods In Free Circulation
Hal Notification Email
Hal Notification Sender Name
Hal Notification Sms
Hold At Location
Hold At Location Address
Hold At Location Facility Id
Hold At Location Release Code
Hold At Location Type
Icod Notification Email
Icod Notification Sender Name
Icod Notification Sms
Import Delivery
Importer Of Record
In Transit Notification Email
Insurance Method
Latest Delivery Date
Location Id
Nah Hal Notification Email
Nah Hal Notification Sender Name
Origin Address
Piece Count
Pre Alert Notification Email
Pre Alert Notification Sender Name
Pre Alert Notification Sms
Proof Require Signature
Proof Require Signature Adult
Proof Return Of Documents
Return Delivery Method
Saturday Delivery
Ship Notification Email
Ship Notification Fax
Shipdate
Shipper
Special Delivery
Subcategory
Terms
Third Party Billing
Third Party Billing Account
Ultimate Consignee
Weight
World Ease Id