shippingapi 1.1.3

Pitney Bowes Shipping API C# Client

This project has the code for a NuGet package that provides a fluent C# interface to the Pitney Bowes Shipping API. The package uses the .NET Standard 2.0 framework, meaning it is compatible with:

• .NET core 2.0
• .NET framework 4.6.1 and above

Mono and Xamarin are also supported.

Features:

• full wrapping of the API. Hides (encapsulates) all protocol details, including authentication and report pagination..
• strong typing – objects for all entities. Enums for all options – which really helps in visual studio intellisense.
• Contract via interfaces as well as DTOs to reduce the need to copy data
• Linq provider for reports
• Fluent interface - less typing and really good way to extend with extension methods
• Support for the metadata provided by the carrier rules method. Use this for local validation/UI options/rate shop.
• Mocking and recording of live messages to disk for capture or later playback in mock mode. Mocking for unit and regression testing.
• Example console app.
• Plug in your own configuration and log providers
• Keeps the API secret out of cleartext

Latest changes - CHANGES

Prerequisites

• To use the C# client to generate shipping labels, you will need a Pitney Bowes Shipping API sandbox account. The account is free and gives access to a fully functional sandbox environment. Sign up for the account here: Shipping API Signup.

  You will need the following information from your Shipping API account. To get the information, see Getting Started.

  • Your API key
  • API secret
  • Developer ID
  • Shipper ID

• VSCode or Visual Studio. The Community Edition of Visual Studio is fine.

• dotnet core 2.0 or later

• git command line (required if building the system out-of-box)

Getting Started

You can get started by doing either of the following:

• Using the NuGet Package
• Building the System Out-of-Box

Using the NuGet Package

If you just want to use the solution without building it, download it from on nuget.org.

If you are developing on Windows, I'd recommend that you install Telerik Fiddler, which will let you see the messages with the Pitney Bowes servers.

1. Build an example app:

   $ mkdir myshippingprojdir
   $ cd myshippingprojdir
   $ dotnet new console
   $ dotnet add package ShippingAPI
   

2. In Visual Studio create a new console app, and then in the package manager console

   PM> install-package ShippingAPI
   

3. Replace your Program.cs file with one of the following from the provided examples:

   • The MyShip.cs sample file. This builds an app that generates a label. The remainder of these steps explain how to configure this app.

   • The Program.cs sample file. This builds an app that that integrates your logging and configuration systems. This also uses all the API's methods. If you use this file, plug in your logging and configuration information appropriately and skip the rest of these steps.

4. Add your own IDs. IDs are case-sensitive. Do one of the following:

   • Replace the values in the code below:

     
     sandbox.AddConfigItem("ApiKey", "your api key");
     sandbox.AddConfigItem("ApiSecret", "your api secret");
     sandbox.AddConfigItem("ShipperID", "your shipper id");
     sandbox.AddConfigItem("DeveloperID", "your developer id");
     

   • Or create a shippingapisettings.json file in %APPDATA% on Windows, or ~ on OSX and Linux:

     { 
         "ApiKey": "!###",
         "ApiSecret": "###",
         "ShipperID": "1234567890",
         "DeveloperID": "1234567890" 
     }
     

5. To create a shipping label:

   var shipment = ShipmentFluent<Shipment>.Create()
       .ToAddress((Address)AddressFluent<Address>.Create()
           .AddressLines("643 Greenway Rd")
           .PostalCode("28607")
           .CountryCode("US")
           .Verify())
      .FromAddress((Address)AddressFluent<Address>.Create()
           .Company("Pitney Bowes Inc")
           .AddressLines("27 Waterview Drive")
           .CityTown("Shelton").StateProvince("CT").PostalCode("06484")
           .CountryCode("US")
           )
      .Parcel((Parcel)ParcelFluent<Parcel>.Create()
           .Dimension(12, 12, 10)
           .Weight(16m, UnitOfWeight.OZ))
      .Rates(RatesArrayFluent<Rates>.Create()
           .USPSPriority<Rates, Parameter>())
      .Documents((List<IDocument>)DocumentsArrayFluent<Document>.Create()
           .ShippingLabel(ContentType.URL, Size.DOC_4X6, FileFormat.PDF))
      .ShipmentOptions(ShipmentOptionsArrayFluent<ShipmentOptions>.Create()
           .ShipperId("your shipper id")    // ******* dont forget this one too *******
           )
      .TransactionId(Guid.NewGuid().ToString().Substring(15));
   
   var label = Api.CreateShipment((Shipment)shipment).GetAwaiter().GetResult();
   if (label.Success)
   {
       var sw = new StreamWriter("label.pdf");
       foreach (var d in label.APIResponse.Documents)
       {
           Api.WriteToStream(d, sw.BaseStream).GetAwaiter().GetResult();
       }
   }
   

Support

If you encounter problems, please contact Support at ShippingAPISupport@pb.com.