Manual

Object-oriented abstraction for eBay's XML API.

Introduction

Introduction – Introduction to Services_Ebay

Introduction to Services_Ebay

Services_Ebay is an object-oriented abstraction layer for eBay's XML API. In addition to a SOAP-service, eBay provides an API, that does not follow any standards except wrapping all webservice calls and parameters in XML. This webservice still is more powerful than eBay's SOAP server and in addition has been heavily tested by real-life applications.

eBay's webservice enables you to use all of eBay's features (except bidding on items) in your own PHP applications. The features range from adding new items to managing the transaction, payment and shipping. Currently there are about 70 method calls available, all accept a range of parameters.

Services_Ebay (as of version 0.7.0) already provides wrappers for 50 methods as well as some model classes which help you working with the results from the calls.

To use this package you will need PHP5 with cURL support enabled and should be familiar with PHP5's exception handling.

Getting started

Getting started – Getting started with the eBay webservice

Developing eBay applications

The eBay webservice is of course not free to use by the public. To develop and test your applications, you will have to register as an eBay developer (which is free of charge). Furthermore, you will not be able to test and develop on the eBay site, before your application has been certified.

The eBay sandbox

The eBay Developers Program Sandbox is a test environment that represents a "mini" eBay site. The Sandbox provides the most important features of the eBay site, allowing you to build and test your application in a non-production environment. The eBay Sandbox supports both API testing as well as site testing via the GUI interface.

While developing your application, you will always be using the eBay sandbox, which can be accessed via web at http://sandbox.ebay.com/. This site looks and behaves like any eBay website you are being used to.

Using the sandbox

To develop applications in the sandbox you will have to register at the eBay developers program. To do this, follow these steps:

Register as an eBay user: In order to register as an eBay developer, you'll have to be an eBay user. As eBay users are valid on all international sites, it is sufficient if you have an eBay user id for your local eBay site, like ebay.com or ebay.de.
Register as an eBay developer: Next, you will have to register as an eBay developer at the eBay developer program. This procedure can take some time, as they require you to enter a lot of information, so you should do this carefully. If you are developing an open source application using Services_Ebay, you should apply for an Individual license. After the registration has been finisehd, you will recieve three keys that you will need to authenticate your eBay application: DevID, AppID and CertID. You will need these keys later so you should save them somewhere.
Create one or more test users: As the sandbox does not share any data with the eBay sites, you will have to create new users that you can use to add items, make transactions and give feedback. You can create as many users as you need for testing purposes, just use the registration form in the sandbox. You will need a valid email address for each of your users, as well as a valid US address and telephone number, you can easily get on by using YellowPages. A credit card is not required, your test users will receive money from eBay they can spend in the sandbox. Of course, this is no real money, which has not use outside of the sandbox.
Validate your test users: If you want your test users to sell items on eBay, you will need to validate them. This can be done using the ValidateTestUserRegistration() API call, which is already supported by Services_Ebay.

Authentication and Authorization

eBay's Auth&Auth process is quite complex and can be the biggest hurdle for getting started with the webservice. To make an API call the following information is required:

DevID (received after registration, unique per developer)
AppID (received after registration, unique per application)
CertID (received after registration, unique per application)
Authentication Token, unique for each user of your application

While you already are in possession of the first three tokens, you still need the last one to make an API call. If your application is used by more than one user (which is the case for web applications), eBay does not want your application to receive the usernames and passwords of your users. If a user authenticates, your application is supposed to redirect him to the eBay login page and pass an additional parameter (a so called RuName). The user will then enter his login information as he is used to on the eBay website and then authorize your application to make API calls on his behalf.

After that, eBay will redirect the user back to your application and pass a unique token, which can be used to identify this user when your application is making API calls. This technique has several advantages:

Single sign-on system for eBay applications
When your application is hacked, no passwords are revealed
The user only sees the login screen he is used to.

As this authentication procedure is quite complex and requires various API calls to function there is an easier way, which can be used for testing. eBay provides the so called Single-User-Tool, an HTML-based tool, which creates tokens that you can use to authenticate a user. All you need to do is submit your DevID, AppID and CertID and select whether the token will be used in the sandbox or production environment.

Getting started with Services_Ebay

Services_Ebay provides a lot of examples, which demonstrate how the API calls have to be used. After installing Services_Ebay, they will be located in the docs/ directory of your PEAR installation. In order to run the examples, you will have to supply the authentication credentials you received from eBay. The easiest way to do this, is to modify the config.php file, which is located in the examples folder.

The configuration file

<?php
// DevID, AppID and CertID
$devId  = 'HFGHSK7JKKJ82JKJFJHF84LKH86Z3JFF71KJKH';

$appId  = 'IUENVCLJEGBN62JLKKLJHD34KKJL-GDJHDGJHD';

$certId = 'GHKL67JKDJLKJGFBNMBCHGDLÖWJH241KKHJKKJ';

// Username and password, only required by some calls
// that set up the Auth&Auth mechanism
$username = 'YourTestUser';

$password = 'Secret Pass';

// Token as returned from the Single-User-Tool
$token = 'AgAAAA.......3jfiEQ**';
?>

XML encoding

XML encoding – XML encoding in Services_Ebay

XML encoding in Services_Ebay

Since mid-2005, the eBay API will only accept UTF-8 encoded XML-documents. As encoding all data to UTF-8 is tedious, Services_Ebay will take care of this for you. All you need to do is specify the encoding you want to use in your script when creating a session object.

Using ISO-8859-1 in your script

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId, 'ISO-8859-1');
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);


$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'International Item';
$item->Description = 'This description contains Umlaut characters like Ä, ü and ß';
$item->Location = 'At my home';
$item->MinimumBid = '532.0'; $item->VisaMaster = 1;
$item->ShippingType = 1;
$item->CheckoutDetailsSpecified = 1;
$item->Country = 'US';
$item->SetShipToLocations(array('US', 'DE', 'GB'));
$item->addShippingServiceOption(1, 1, 3, 1, array('US'));

$result = $ebay->AddItem($item);
?>

The umlaut characters contained in the description of the item will be automatically converted to UTF-8 when the XML-document is created. Furthermore the result document which is returned by the eBay API will be decoded again to ISO-8859-1 so you do not have to worry about UTF-8 at all.

Of course, it is also possible to supply UTF-8 encoded data to Services_Ebay. All you have to do is change the encoding type, when creating the session object.

Using UTF-8 in your script

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId, 'UTF-8');
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);


$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'International Item';
$item->Description = utf8_encode('This description contains Umlaut characters like Ä, ü and ß');
$item->Location = 'At my home';
$item->MinimumBid = '532.0'; $item->VisaMaster = 1;
$item->ShippingType = 1;
$item->CheckoutDetailsSpecified = 1;
$item->Country = 'US';
$item->SetShipToLocations(array('US', 'DE', 'GB'));
$item->addShippingServiceOption(1, 1, 3, 1, array('US'));

$result = $ebay->AddItem($item);
?>

In this example you are using utf8_encode() to encode the data prior to passing it to Services_Ebay. To avoid duplicated encoding, you need to set the encoding to UTF-8.

Error Handling

Error Handling – Error Handling in Services_Ebay

Exceptions in Services_Ebay

As Services_Ebay is a PHP 5 only package, it uses exception handling and the PEAR_Exception class as base class for all exceptions. Exceptions can be thrown, whenever you try to call any of the API calls provided by Services_Ebay, which means you should always nest those in a try/catch-block:

Exception handling

<?php
require_once 'Services/Ebay.php';
    
// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);
try {
    // call a method
    echo $ebay->GeteBayOfficialTime();
} catch (Exception $e) {
    echo "Something went wrong.";
    echo $e;
}
?>

When calling a non-existent API call or passing the wrong parameters to the API, eBay will abort the API call and return an XML-document that contains error information. Services_Ebay will automatically convert this into an exception that can be easily handled by your PHP application.

Warnings in Services_Ebay

In some cases, the eBay API will still process your request, even if you passed invalid parameters and include error information in the resulting XML-document alongside the actual response of your request.

In this case, the errors will be tagged as warnings, as they were not serious errors. Services_Ebay will not convert these errors to exceptions, but only to instances of Services_Ebay_Error. These objects will be stored in the Services_Ebay_Session and can be retrieved by your application at a later point.

Handling warnings

<?php
require_once 'Services/Ebay.php';
    
// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);
try {
    // call a method
    echo $ebay->GeteBayOfficialTime();
} catch (Exception $e) {
    // Just ignore the exception and handle them
    // with any warnings, that might have occured.
}

$errors = $session->getErrors();
if (count($errors) == 0) {
    echo "No errors or warnings.\n";
} else {
    foreach ($errors as $error) {
        printf("%s: %s (%d))\n", $error->getSeverity(), $error->getLongMessage(), $error->getCode());
    }
}
?>

Architecture

Architecture – The architecture of Services_Ebay

Overview of Services_Ebay architecture

Services_Ebay consists of a lot of small classes, which keeps the used codebase small, as only the functionality that you use in your applications are loaded and parsed.

This will give you a short overview of the different types of objects that are provided and for which tasks they are used.

Services_Ebay

The Services_Ebay class is used for the following tasks:

Provides factory methods. The Services_Ebay provides methods to load and instantiate all of the other classes, that are included in the Services_Ebay distribution. That means that this is the only class you should include and instantiate yourself. Factory methods include loadApiCall(), getSession() and loadModel().
Provides constants. This class also defines some constants like the eBay site ids that you will need in your applications, constants include Services_Ebay::SITEID_ID, Services_Ebay::AUTH_TYPE_TOKEN or Services_Ebay::FEEDBACK_BRIEF. Whenever the eBay webservice expects an integer value in an XML tag, Services_Ebay tries to provide a matching constant.
Provides static helper methods. The class also provides some helper methods, which can be called statically like getAvailableApiCalls().
Acts as a proxy class. The most important usage is that Services_Ebay acts as a proxy class for the API calls, that means you can call methods on the class which will then be redirected to the appropriate call object.

Services_Ebay_Session

The Services_Ebay_Session class is used to handle the serialization and unserialization of the incoming and outgoing XML streams. Furthermore it builds the HTTP headers that are needed and manages all user authentication.

You will probably always use the session indirectly by at first passing it to the Services_Ebay object which will then use the session for making API calls.

Using the session class

<?php
require_once 'Services/Ebay.php';
    
// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object with the instantiated session
$ebay = new Services_Ebay($session);
?>

Services_Ebay_Transport

The Services_Ebay_Transport classes are used to build up network connections to the eBay webservices and send and recieve the raw data which has been created by Services_Ebay_Session.

Theoretically there may be different transport classes, but due to bugs in PHP's stream functions and some SSL libraries, the only working transport class is Services_Ebay_Transport_Curl, which uses PHP's curl extension.

Services_Ebay_Call

The Services_Ebay_Call classes contain information about the API calls that the eBay webservice offers. Each API call is encapsulated in an object that contains information about the API call, which XML tags have to be used and what the call is expected to return.

There are two ways in which the call objects can be used:

Instantiate them directly (best via the factory method of Services_Ebay), pass all parameters and invoke Services_Ebay_Call::call() while passing the session object to this method.
Use Services_Ebay as a proxy object which is able to do all the work by using PHP5's new object overloading features.

It is recommended to use Services_Ebay as a proxy instead of working directly on the Call objects. Services_Ebay will instantiate the class, pass the parameters and invoke the call method on the Call object.

Services_Ebay_Model

The Services_Ebay_Model classes act as local containers for the remote data stored on the eBay server. For example, when calling Services_Ebay::getItem(), the method will return an instance of Services_Ebay_Model_Item, which contains information about the item as well as some helper methods like Services_Ebay_Model_Item::addToDescription() which encapsulates a new API call.

Currently Services_Ebay provides models for accounts, disputes (single dispute and a list of disputes), user feedback (summary and a single feedback entry), items and list of items, MyeBay, orders, preferences, search results, shipments, eBay stores, transactions and users.

Services_Ebay_Cache

The Services_Ebay_Cache classes allow you to locally cache information that you retrieved from the eBay webservice without changing anything in your scripts. After registering a cache instance for any model type, Services_Ebay will query the cache before making a time-consuming API call.

The cache classes use a very high abstraction and allow you to create new cache containers, so you could store the data in a database, shared memory or wherever you like. Currently there is only one container available, which stores the data in the local filesystem.

To determine, whether a cache is still valid an instance of Services_Ebay_Cache_ExpiryCheck is used, which allows you to build "intelligent" caches that have a shorter expiry time the nearer the end of an auction is.

Example

Example – Basic example of Services_Ebay

Basic example of Services_Ebay

The following examples show how to use some basic features of Services_Ebay:

Using a proxy object

<?php
require_once 'Services/Ebay.php';
    
// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);

// call a method
echo $ebay->GeteBayOfficialTime();
?>

Working directly with a Call object

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

$call = Services_Ebay::loadAPICall('GetEbayOfficialTime');
$result = $call->call($session);

echo $result;
?>

Using the model classes

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// get an eBay item
$item = $ebay->GetItem(4501333179, 2);

// The Seller property is an object as well
echo 'User-Id of the seller: '.$item->Seller->UserId.'<br />';

// convert the item to an array 
echo '<pre>';
print_r($item->toArray());
echo '</pre>';

// Use methods of the model
$item->AddToDescription('I forgot some important information');

// Change the item
$item->Title = 'The new title of the item';

$ebay->ReviseItem($item);
?>