eBay Trading API: API Flow Tutorial
|
This tutorial demonstrates how an application gets a token for a user.
The first step is the preparatory setup that enables an application to receive user tokens. This setup is done on the eBay Developers Program site (developer.ebay.com).
The second step involves interactions between an application and a user:
The application makes several API calls to eBay during the process of getting a token. When a step includes an API call, it provides a link to XML call samples in the Trading API Call Reference. The samples show how to perform those steps using the API.
This tutorial contains the following sections:
The API Flow tutorials use raw XML requests and responses. The XML call samples described in this tutorial can all be found in the Trading API Call Reference.
All the calls in the tutorial are performed in the Sandbox environment, using a test user and the API Test Tool. If you want to perform the steps in this tutorial for your own application in the Sandbox, you'll need to do the following:
Join the eBay Developers Program and get your application key set.
Create your own Sandbox test user, equivalent to the testuser Magical Bookseller used in this scenario, with a Sandbox authentication token. See "Using the Sandbox" in the Trading API Guide for more information.
Have an application that can respond to web-based user actions and receive responses to calls it makes to eBay servers.
The tutorial has no specific code requirements. You can run the XML samples in the API Test Tool on the eBay Developers Program website (you must log in).
Typically, an application needs to be set up to receive tokens only once.
This section shows how the developer of MagicLister uses the forms in the application settings tab, in the My Account page, to:
Configure a consent form that MagicLister's subscribers will use to grant MagicLister tokens
Generate an RuName that MagicLister will use in the token generation process.
The developer signs in to developer.ebay.com and goes to his My Account page. He selects the application settings tab, where he does the following:
Selects an environment (Sandbox, in this case).
Selects the keyset for the MagicLister application.
Configures application level settings that customize the user consent flow. He opts to show application details, and supplies the MagicLister URL and the MagicLister logo.
Under "Manage Your RuNames," he clicks "Generate RuName." After a minute or so, the page refreshes with a success message and a new RuName. An RuName contains settings that govern:
The content that users will see on the consent form
Rules about how the application authenticates users and gets tokens
Application URLs such as the AcceptURL that eBay uses to return consenting users to the application
Under "Manage Your RuNames," he clicks "Show Details" for the new RuName. This opens the form where he sets up application consent details:
For more information about the fields in this form, click a field for a popup description. Also see Configuring the Consent Flow for Applications with Multiple Users.
After making changes, click Save Settings.
The MagicLister application is now set up to start getting tokens.
This section shows:
Magical Bookseller goes to the MagicLister site, where she clicks a Subscribe button or otherwise lets the application know that she intends to use it.
MagicLister sends a GetSessionID call to eBay, with the MagicLister RuName.
GetSessionID: retrieves a SessionID that will identify Magical Bookseller after she signs in to eBay.
GetSessionID returns a SessionID to MagicLister.
MagicLister URL-encodes the SessionID and then constructs a URL containing the SessionID and the RuName, and uses this URL to send Magical Bookseller to the eBay Sandbox sign-in page. In this scenario, the GetSessionID call was made using the API Test Tool, and the SessionID was pasted into a URL along with MagicLister's RuName, in a browser window.
The URL takes this form:
https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=YourRuNameHere&SessID=YourSessionIDHere
Magical Bookseller signs in to eBay.
eBay sends Magical Bookseller to the user consent form that MagicLister configured in the application settings tab, in the first section of this scenario.
When Magical Bookseller clicks "I agree," eBay sends her to MagicLister's AcceptURL.
When Magical Bookseller arrives at its AcceptURL, MagicLister sends a FetchToken request to eBay with the SessionID.
FetchToken: retrieves the token.
Notice that MagicLister includes its credentials with this FetchToken call--the developer ID, the application ID, and the AuthCert. That's because this is one of the few authenticated user-related calls that you make when you don't already have a token. If you're using SOAP, the credentials need to be in the SOAP header; for XML you include them in the RequesterCredentials field in the request body.
FetchToken returns a user token for Magical Bookseller to MagicLister.
MagicLister saves the token and the token expiration date from the FetchToken response.
MagicLister tests the token by making a GeteBayOfficialTime request using the new token.
This section contains notes about the tutorial and suggestions for extending it.
Here are some suggestions for ways you could modify or extend the tutorial to learn more about the API:
Try other calls for the user: Listing an Item, Buying an Item, or Completing a Sale.
Make a GetUser call.
Try the procedure with your application in Production: create a testuser, subscribe it to your application, and get a token for the user.
eBay Knowledge Base includes applications that incorporate the process of getting user tokens. The applications are here:
More information about the eBay Trading API is available at these locations:
Share tips or code samples related to this call or document. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they're pertinent to the document and relevant to the community. Your submission will show up for all developers when it's activated by the moderator.
Copyright © 2009–2013 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.