f you’re involved in creating applications for manufacturing or retailing organizations, unless those businesses are the size of roadside taco stands, you probably already have some kind of inventory management system?more than likely built around a product database. In the code download for the sample project that accompanies this article, I’ve included a very simple example inventory database in Microsoft Access format (of course, your real database can be any type). This sample project that accompanies this article uses this inventory database as the basis for the integration project.
As with any kind of integration project, the task involves writing a little glue code to make your existing system communicate with an external service. Sprinkling a little XML and HTTP pixie dust helps make this go more smoothly, as you probably know.
Figure 1 contains a high-level diagram that shows how all the pieces fit together.
The Inventory Integration Utility The inventory integration utility is a VB .NET Windows Forms application with two DataGrid controls and two buttons (see Figure 2). The left DataGrid contains a list of items in the local inventory system. The application retrieves that information from the local database using a conventional query (the control is bound to an ADO.NET DataSet).
On the right side of the form is another DataGrid containing the items your company currently lists for sale on eBay. That grid will be empty the first time you run the application, but it will fill up with data as you list items. The grid gets its data by retrieving an XML document from eBay through a call to the eBay SDK.
Making eBay SDK Calls After creating the ApiSession object you use it to place other calls to the eBay SDK. To list an item, you first retrieve the item’s data from the local inventory database, including the item’s name, description, and perhaps other data about the item such as its physical location and selling price. For this sample application, you need only retrieve the item’s name and description from the database using the following ADO.NET query:
Dim cn As IDbConnection = GetConnection() Dim da As OleDbDataAdapter Dim theSql As String theSql = "SELECT ID, Name, Description " & _ "FROM tblProduct " & _ "WHERE ID = " & CurrentItemID Dim ds As DataSet = New DataSet("Product") da = New OleDbDataAdapter(theSql, cn) da.Fill(ds) cn.Close()
The value CurrentItemID in the preceding code fragment gets set when the user clicks on a row in the DataGrid control.
Now that you have the information about the item you want to list, you can send it off to eBay. Do this by first creating an instance of an IItem object (found in the eBay.SDK.Model.Item namespace). This object represents, not surprisingly, the item to be listed on eBay; it contains properties that describe the item and the item’s listing format. The listing format is important, because not all eBay listings are auctions ?you can sell an item in a fixed-price format as well, a convenience that many buyers appreciate.
When I create an eBay SDK application, I typically create a function that specifically creates and returns an IItem. Here’s an example of such a function:
Private Function CreateItem(ByVal title As String, ByVal description As String) As IItem Dim it As IItem = New eBay.SDK.Model.Item.Item With it .SiteId = SiteIdEnum.US .Type = ItemTypes.Auction .Title = title .Description = description .Currency = CurrencyEnum.USDollar .Location = "San Jose, CA" .Country = "us" .CategoryId = 14111 ' test auctions:general .Quantity = 1 .Duration = 7 .MinimumToBid = 0.01 .BuyItNowPrice = 15.0 .ReservePrice = 0 .PaymentTerms.SeeDescription = True .ShippingOptions.ShippingRange = _ ShippingRangeEnum.SiteOnly .Uuid = New Uuid(True) End With Return it End Function
Obviously, in this example, many of the values are hard-coded. In a real application, you’d retrieve data for properties like Location and MinimumBid from the database, or perhaps even from the registry or App.Config.
CategoryId is an interesting property. This example uses eBay’s test category, which exists specifically for software developers and others who want to experiment. But eBay has more than 30,000 product categories, with more being added every month. If you want to incorporate this category hierarchy in your application, you can do so by downloading it in XML format (use the GetCategories method to obtain the category list).
Sending an Item to eBay Returning to the task at hand, you now have an ApiSession object that has your identity assigned to it, as well as an IItem object that has been populated with data. All that remains is to send the item to eBay. Here’s how to do that:
Dim ai As AddItemCall = New AddItemCall(sess) With ai .ItemToAdd = it .ErrorLevel = _ ErrorLevelEnum.BothShortAndLongErrorStrings Try Dim fees As IFees = ai.AddItem() Status.Text = _ "Listed item successfully. " & _ "eBay item ID is " & ai.ItemToAdd.ItemId.ToString() & ". " & "Listing fee is " & fees.InsertionFee.ToString() & "." Catch ex As APIException MessageBox.Show("API exception in " & _ "AddItem. [" + ex.Message + "]") Catch ex As Exception MessageBox.Show("Exception in AddItem." & _ " [" + ex.Message + "]") End Try End With
To send the item to eBay, you create an instance of an API wrapper class called AddItemCall, passing the ApiSession object we created previously into the AddItemCall object’s constructor. Then, assign the IItem object to the ItemToAdd property and tell the object that you want to receive verbose error data if anything goes wrong. Finally, start a Try…Catch block because you’re about to subject the item to the vagaries of the Internet and you need to make sure that the application reports any errors that occur to the user in a reasonable fashion.
Interestingly, the AddItem method? returns a new kind of object, IFees. This object tells the user what it costs to list the item for sale on eBay.
If you’ve never used eBay to sell items, eBay charges sellers to list items at the time the item is listed and again when the item is sold. These charges don’t apply when you’re developing applications in the sandbox, of course, so feel free to list items there until the cows come home.
At this point you’ve cut the amount of time it takes to list an item from several minutes down to a few seconds. But the whole point here is to enable you to accelerate your business by blasting your inventory onto eBay. So how can you keep track of all the items you have for sale?
One method to retrieve a comprehensive list of all the items you’ve listed on eBay is to call the GetSellerList method. While it’s possible and sometimes useful to retrieve this information as a typed collection, when displaying collections of IItem objects in Windows Forms I use a trick that lets my application get to the raw XML data behind the wrapper class. In VB.NET you do this by declaring the GetSellerListCall object using the WithEvents keyword, and then handling the OnReceiveResponseXml event of the GetSellerListCall object.
Here’s the call to GetSellerList that retrieves all this data:
Private WithEvents slc As GetSellerListCall slc = New GetSellerListCall( _ sc.CreateSession()) With slc .Timeout = 60000 ' In the following line, ' 32 is a medium abbreviated result set .DetailLevel = 32 .EndTimeFrom = DateTime.Now.ToUniversalTime() .EndTimeTo = slc.EndTimeFrom.AddDays(120) .PageNumber = 1 .ItemsPerPage = 100 End With Dim items As IItemCollection items = slc.GetSellerList
Note that the DetailLevel property gives you have a number of options for retrieving data from eBay. You don’t have to perform an excruciating call to repeatedly download the complete set of data associated with hundreds of items; it’s better to choose a specific detail level to retrieve only that information you need. For example, detail level 2 retrieves the eBay IDs for all the items you’re selling (and not much else). So if you cleverly stored the eBay ID for the listing somewhere in your database at the time you listed the item, you don’t have to call the heavyweight version of GetSellerList over and over again to retrieve information you already have. When you’re jumping across the Internet to retrieve large XML result sets, it’s handy to have some granular control over how much data gets retrieved for each context.
If you want to see the item page on eBay (to bid on it, perhaps, or to see how your listing looks), you can launch an instance of the default Web browser using this single line of code in .NET:
Note that this URL works for items you’ve listed in the development sandbox; you’ll need to change this URL for the production eBay.com site.
So that’s basically it. The sample project accesses and lists the current items in the inventory database, lets users move items from that inventory list to eBay, and lets them retrieve status updates on the listed items. The user interface is simple and efficient so that users need only click a few times to make the magic happen.
This article only covered two of the fifty or so calls in eBay’s API repertoire, but these are two of the most important. Having mastered these, you won’t have any trouble with the others. I hope that seeing these in action will give you a sense of how easy it is to integrate your business with eBay.