Executing Your First C# Call

This section walks through the basics of executing a call—specifically, the GetUser call for the eBay SOAP API. The GetUser call is the simplest call in the API. It can be used to synchronize the time in your system with eBay official time or as a simple way to verify whether you are communicating with the eBay API servers.

These are the basic steps:

Step 1: Set Up a Programming Environment

Step 2: Add the Code

Step 3: Run the Sample

Step 4: Understand the Example

Step 5: Understand the SOAP Messages

The code examples in this chapter are in C#, however, you can use almost any language to access the eBay SOAP API.

Prerequisites

Before you execute your first SOAP API call:

Have a Sandbox test user ready. (Only test users can invoke calls in the Sandbox.)
To register a test user, see Create a test Sandbox user.
Have the authentication token ("auth token") ready for that test user.
Obtain an authentication token for the test user (see Sandbox). You must have a token in order to make any calls to the Trading API.

Step 1: Set Up a Programming Environment

The specific steps that you must perform to set up your environment will vary depending on what programming language you use. One important requirement common to all languages is support for SSL. This example was written in C# Microsoft Visual Studio .NET.

In Visual Studio, create a project file, then add a web reference to it (Solution Explorer, right-click, Add Web Reference). Enter the URL to the latest eBay WSDL:

https://developer.ebay.com/webservices/latest/ebaySvc.wsdl

Then, click Add Reference. This generates stubs from the eBay WSDL and adds them to the project so that they are available to your source files. You can see them in the Class View.

Step 2: Add the Code

Now you will add the code that calls the SOAP API. Create a source file named GetUser.cs and paste the following code into it.

Example 3-1 GetUser.cs

using System;
using TesteBaySoap1207.com.ebay;     // use your project name here
namespace TesteBaySoap1207           // use your project name here
{
  class GetUser
  {
    [STAThread]
    static void Main(string[] args)
    {
       string endpoint = "https://api.sandbox.ebay.com/wsapi";
       string callName = "GetUser";
       string siteId = "0";
       string version = "1207";
       // Build the request URL
       string requestURL = endpoint
       + "?callname=" + callName
       + "&siteid=" + siteId
       + "&version=" + version
       + "&routing=default";
       // Create the service
       eBayAPIInterfaceService service = new eBayAPIInterfaceService();
       // Assign the request URL to the service locator.
       service.Url = requestURL;
      // Set credentials
      service.RequesterCredentials = new CustomSecurityHeaderType();
      service.RequesterCredentials.eBayAuthToken = "yourToken";    // use your token
      service.RequesterCredentials.Credentials = new UserIdPasswordType();
      // Make the call to GetUser
      GetUserRequestType request = new GetUserRequestType();
      request.Version = "1207";
      GetUserResponseType response = service.GetUser(request);
      Console.WriteLine("The eBay time returned is:");
      Console.WriteLine(response.Timestamp);
    }
  }
}

You must modify some of the code with your information in order for it to work:

Use your project name in the using and namespace statements at top.
Add your token.

Step 3: Run the Sample

Now you can build and run the sample.

From the menu, choose Build, then Build Solution.
Choose Debug, then Start Without Debugging.

You should see output like this:

  The eBay time returned is:
  5/02/2025 07:22:54Z 
  Press any key to continue

Step 4: Understand the Example

This sample takes four basic steps that you need to use in any client application that calls the eBay web service. The web service client should:

Build the request URL that contains the location of the eBay web service, the call name, and other parameters that make the call.
The request URL should contain the URL to the eBay service, the call name, the site ID, your application ID, the WSDL version number, and the special parameter routing=default. The routing=default ensures that your call reaches the eBay single-namespace WSDL.

Example 3-2 Build the Request URL
```
       string endpoint = "https://api.sandbox.ebay.com/wsapi";
       string callName = "GetUser";
       string siteId = "0";
       string version = "1207";
       // Build the request URL
       string requestURL = endpoint
       + "?callname=" + callName
       + "&siteid=" + siteId
       + "&version=" + version
       + "&routing=default";
```
Create a service locator object and pass it the request URL.
The service object that is an instance of eBayAPIInterfaceService allows you to make the call. You need to create it and pass it the request URL.

Example 3-3 Create the Service Locator Object
```
       // Create the service
       eBayAPIInterfaceService service = new eBayAPIInterfaceService();
       // Assign the request URL to the service locator.
       service.Url = requestURL;
```
Set credentials.
This part of the sample sets your authentication token and your three Sandbox keys. You can choose to hard-code them for a test call, read them from a properties file, or use some other technique, but they must be set in CustomSecurityHeaderType and UserIdPasswordType.

The token must be current and correct for the Sandbox keys. If your token has expired, the call will return an error. In that case, obtain a new token.

Example 3-4 Set Credentials
```
      // Set credentials
      service.RequesterCredentials = new CustomSecurityHeaderType();
      service.RequesterCredentials.eBayAuthToken = "yourToken";    // use your token
      service.RequesterCredentials.Credentials = new UserIdPasswordType();
```
Make the call.
For the call you plan to use, create an instance of the request type. Set its Version variable and any other variables that are required or important for the call. Then, create an instance of the response type. Make the call on the service object, passing it the request object and storing the result in the response object.

You can also write similar lines that execute a different call here. Make sure to set all needed variables in the request object. If you are making a call that involves buying, selling, or obtaining user information, you must create test users in the Sandbox first (See Sandbox for more information).

Example 3-5 Make the Call
```
      // Make the call to GetUser
      GetUserRequestType request = new GetUserRequestType();
      request.Version = "1207";
      GetUserResponseType response = service.GetUser(request);
      Console.WriteLine("The eBay time returned is:");
      Console.WriteLine(response.Timestamp);
```

Step 5: Understand the SOAP Messages

The SOAP request message to GetUser looks like Example 3-6. The credentials are set in the SOAP header according to the structure of RequesterCredentials in the eBay WSDL, while the request to GetUser is made in the SOAP body.

Example 3-6 SOAP Request Message

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <RequesterCredentials soapenv:mustUnderstand="0" xmlns="urn:ebay:apis:eBLBaseComponents">
       <eBayAuthToken>ABC...123</eBayAuthToken>
       <ns:Credentials xmlns:ns="urn:ebay:apis:eBLBaseComponents">
       </ns:Credentials>
    </RequesterCredentials>
  </soapenv:Header>
  <soapenv:Body>
    <GetUserRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <ns1:Version xmlns:ns1="urn:ebay:apis:eBLBaseComponents">1207</ns1:Version>
    </GetUserRequest>
  </soapenv:Body>
</soapenv:Envelope>

The SOAP response from GetUser looks like Example 3-7. Note that the response in the SOAP body contains the eBay time returned defined in GetUser and also values (such as Ack, Version, and Build) defined in AbstractResponseType.

Example 3-7 SOAP Response Message

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <GetUserResponse xmlns="urn:ebay:apis:eBLBaseComponents">
      <Timestamp>2025-05-02T00:07:22.895Z</Timestamp>
      <Ack>Success</Ack>
      <Version>1207</Version>
      <Build>E1207_CORE_APISIGNIN_19151597_R1</Build>
      <User>
      <AboutMePage>false</AboutMePage>
      ...
      <EnterpriseSeller>false</EnterpriseSeller>
    </User>
    </GetUserResponse>
  </soapenv:Body>
</soapenv:Envelope>