{"id":33,"date":"2021-02-13T03:18:53","date_gmt":"2021-02-13T03:18:53","guid":{"rendered":"https:\/\/jonrocket.com\/zencart\/?p=33"},"modified":"2021-02-13T17:46:39","modified_gmt":"2021-02-13T17:46:39","slug":"under-the-hood-the-ebay-api","status":"publish","type":"post","link":"https:\/\/jonrocket.com\/zencart\/2021\/02\/13\/under-the-hood-the-ebay-api\/","title":{"rendered":"eBay Integration – the eBay API"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Integration with eBay is made possible by the eBay Application Program Interface (API)<\/a> which is a collection of services that expose methods that can be called from your server to access information and to define notifications to be sent by eBay to your server.<\/p>\n\n\n\n

What this means is that the eBay Integration plug-in for Zen Cart, running on your server, can access your account data at eBay. It can create listings, get notified of orders, update listings, and more. <\/p>\n\n\n\n

In order to do all these neat things, the plug-in has to get permission to access the API and your data. The plug-in accesses the API by making RESTfull calls<\/a> to eBay’s servers using the same HTTP protocol<\/a> that your browser uses to get a web page from a web site or submit a form to it.<\/p>\n\n\n\n

In order to use the API, the plug-in needs permission to access it. eBay uses three identifiers as keys – sort like a user ID and password – to let your plug-in call the API methods. The keys are assigned to your application (the plug-in). To create the keys, you have to create an account at eBay’s Developer web site and register your application<\/a>.<\/p>\n\n\n\n

The keys give the plug-in permission to call the eBay API methods, but only to get public information. To get access to your eBay account information, the plug-in needs to get a security token<\/a>.<\/p>\n\n\n\n

The security token grants permission to the plug-in allowing it to access the account information that it needs.<\/p>\n\n\n\n

To talk to the eBay API, the plug-in uses a slightly-updated version of a PHP<\/a> class written by eBay. The eBaySessionHandler <\/strong>class (called just eBaySession<\/a><\/strong> by eBay) encapsulates the code for sending a request to an eBay server and receiving the response.<\/p>\n\n\n

\/**\n *  eBay's PHP code for making API calls\n *\/<\/span>\nclass<\/span> eBaySessionHandler<\/span>\n <\/span>{\n  var<\/span> $devID;\n  var<\/span> $appID;\n  var<\/span> $certID;\n  var<\/span> $serverUrl;\n  var<\/span> $compatLevel;\n  var<\/span> $siteID;\n  var<\/span> $verb;\n\n  \/**\n   * __construct\n   * Constructor to make a new instance of eBaySessionHandler with the details needed to make a call\n   * Note that authentication credentials (normally token, but could be username and password)\n   * are assumed to come in the request body, and not in the constructor args\n   * Input: $developerID - Developer key obtained when registered at http:\/\/developer.ebay.com\n   * $applicationID - Application key obtained when registered at http:\/\/developer.ebay.com\n   * $certificateID - Certificate key obtained when registered at http:\/\/developer.ebay.com\n   * $severUrl - URL of the server to use\n   * $compatabilityLevel - API version this is compatable with\n   * $siteToUseID - the Id of the eBay site to associate the call iwht (0 = US, 2 = Canada, 3 = UK, ...)\n   * $callName - The name of the call being made (e.g. 'GeteBayOfficialTime')\n   * Output: Response string returned by the server\n   *\/<\/span>\n  function<\/span> __construct<\/span>($developerID, $applicationID, $certificateID, $serverUrl, $compatabilityLevel, $siteToUseID, $callName)<\/span>\n   <\/span>{\n    \/\/ $this->requestToken = $userRequestToken;<\/span>\n    $this<\/span>->devID = $developerID;\n    $this<\/span>->appID = $applicationID;\n    $this<\/span>->certID = $certificateID;\n    $this<\/span>->compatLevel = $compatabilityLevel;\n    $this<\/span>->siteID = $siteToUseID;\n    $this<\/span>->verb = $callName;\n    $this<\/span>->serverUrl = $serverUrl;\n   }\n\n  \/**\n   * sendHttpRequest\n   * Sends a HTTP request to the server for this session\n   * Input: $requestBody\n   * Output: The HTTP Response as a String\n   *\/<\/span>\n  function<\/span> sendHttpRequest<\/span>($requestBody)<\/span>\n   <\/span>{\n    \/\/ build eBay headers using variables passed via constructor<\/span>\n    $headers = $this<\/span>->buildEbayHeaders ();\n\n    \/\/ initialise a CURL session<\/span>\n    $connection = curl_init ();\n    \/\/ set the server we are using (could be Sandbox or Production server)<\/span>\n    curl_setopt ( $connection, CURLOPT_URL, $this<\/span>->serverUrl );\n\n    curl_setopt ( $connection, CURLOPT_TIMEOUT, 30<\/span> );\n\n    \/\/ stop CURL from verifying the peer's certificate<\/span>\n    curl_setopt ( $connection, CURLOPT_SSL_VERIFYPEER, 0<\/span> );\n    curl_setopt ( $connection, CURLOPT_SSL_VERIFYHOST, 0<\/span> );\n\n    \/\/ curl_setopt($connection, CURLOPT_HEADER, 1 ); \/\/ Uncomment these for debugging<\/span>\n    \/\/ curl_setopt($connection, CURLOPT_VERBOSE, true); \/\/ Display communication with serve<\/span>\n\n    curl_setopt ( $connection, CURLOPT_TIMEOUT, 360<\/span> );\n\n    \/\/ set the headers using the array of headers<\/span>\n    curl_setopt ( $connection, CURLOPT_HTTPHEADER, $headers );\n\n    \/\/ set method as POST<\/span>\n    curl_setopt ( $connection, CURLOPT_POST, 1<\/span> );\n\n    \/\/ set the XML body of the request<\/span>\n    curl_setopt ( $connection, CURLOPT_POSTFIELDS, $requestBody );\n\n    \/\/ set it to return the transfer as a string from curl_exec<\/span>\n    curl_setopt ( $connection, CURLOPT_RETURNTRANSFER, 1<\/span> );\n\n    \/\/ Send the Request<\/span>\n    $response = curl_exec ( $connection );\n\n    \/\/ print curl_error($connection) . \": \" . $response;<\/span>\n\n    \/\/ close the connection<\/span>\n    curl_close ( $connection );\n\n    \/\/ return the response<\/span>\n    return<\/span> $response;\n   }\n\n  \/**\n   * buildEbayHeaders\n   * Generates an array of string to be used as the headers for the HTTP request to eBay\n   * Output: String Array of Headers applicable for this call\n   *\/<\/span>\n  function<\/span> buildEbayHeaders<\/span>()<\/span>\n   <\/span>{\n    $headers = array<\/span> ( \/\/ Regulates versioning of the XML interface for the API<\/span>\n      'X-EBAY-API-COMPATIBILITY-LEVEL: '<\/span> . $this<\/span>->compatLevel,\n\n      \/\/ set the keys<\/span>\n      'X-EBAY-API-DEV-NAME: '<\/span> . $this<\/span>->devID,\n      'X-EBAY-API-APP-NAME: '<\/span> . $this<\/span>->appID,\n      'X-EBAY-API-CERT-NAME: '<\/span> . $this<\/span>->certID,\n\n      \/\/ the name of the call we are requesting<\/span>\n      'X-EBAY-API-CALL-NAME: '<\/span> . $this<\/span>->verb,\n\n      \/\/ SiteID must also be set in the Request's XML<\/span>\n      \/\/ SiteID = 0 (US) - UK = 3, Canada = 2, Australia = 15, ....<\/span>\n      \/\/ SiteID Indicates the eBay site to associate the call with<\/span>\n      'X-EBAY-API-SITEID: '<\/span> . $this<\/span>->siteID\n    );\n\n    return<\/span> $headers;\n   }\n }\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
I added classes to encapsulate handling of the specific eBay requests that the plug-in uses.  All are derived from a base class I called eBayRequest<\/strong>.<\/p>\n\n\n
\/**\n *  An eBay request\n *\/<\/span>\nabstract<\/span> class<\/span> eBayRequest<\/span>\n <\/span>{\n  private<\/span> $requestType;\n\n  \/**\n    *  @brief<\/span> Constructor\n    *   \n    *  @param<\/span> string $requestType the eBay API request type\n    *  @return<\/span> void\n    *\/<\/span>\n  function<\/span> __construct<\/span>($requestType)<\/span>\n   <\/span>{\n    $this<\/span>->requestType = $requestType;\n   }\n\n  \/**\n    *  @brief<\/span> getXML - return the XML used to make the API the call\n    *  \n    *  @return<\/span> string the XML of the call\n    *\/<\/span>\n  abstract<\/span> protected<\/span> function<\/span> getXML<\/span>()<\/span><\/span>;\n\n  \/**\n   *  @brief<\/span> addResults - add results to the list of results\n   *  \n   *  @param<\/span> string $xml the output XML from the API call\n   *  @param<\/span> array $results the array to hold the $results\n   *  @return<\/span> array the array of results\n   *\/<\/span>\n  abstract<\/span> protected<\/span> function<\/span> addResults<\/span>($xml, $results)<\/span><\/span>;\n\n  \/**\n   *  @brief<\/span> getServerURL - return the URL of the API call\n   *  \n   *  @return<\/span> sting the URL\n   *\/<\/span>\n  protected<\/span> function<\/span> getServerURL<\/span>()<\/span>\n   <\/span>{\n    return<\/span> \"https:\/\/api.ebay.com\/ws\/api.dll\"<\/span>;\n   }\n\n  \/**\n   *  @brief<\/span> getResults - make the actual API call and return the results\n   *\n   *  @param<\/span> boolean|array - if true, error messages are not logged.  If an array, \n   *                         messages are logged only for errors not in the array \n   *                         of error codes.\n   *  \n   *  @return<\/span> array the results\n   *\/<\/span>\n  public<\/span> function<\/span> getResults<\/span>($suppressErrors = false)<\/span>\n   <\/span>{\n    $devID = ebayGetConfiguration ( 'PROD_DEVID'<\/span> );\n    $appID = ebayGetConfiguration ( 'PROD_APPID'<\/span> );\n    $certID = ebayGetConfiguration ( 'PROD_CERTID'<\/span> );\n    $serverUrl = $this<\/span>->getServerURL ();\n    $compatabilityLevel = 705<\/span>;\n    $siteID = 0<\/span>;\n    $verb = $this<\/span>->requestType;\n\n    $session = new<\/span> eBaySessionHandler ( $devID, $appID, $certID, $serverUrl, $compatabilityLevel, $siteID, $verb );\n\n    $xml = $this<\/span>->getXML ();\n    \n    if<\/span> (function_exists('eBayModifyRequest'<\/span>))\n      {\n        $xml = eBayModifyRequest($verb, $xml);\n      }\n\n    $response = $session->sendHttpRequest ( $xml );\n\n    $results = array<\/span> ();\n\n    $results ['count'<\/span>] = 0<\/span>;\n    $results ['errorcode'<\/span>] = '0'<\/span>;\n    $results ['errormessage'<\/span>] = ''<\/span>;\n    if<\/span> (stristr ( $response, 'HTTP 404'<\/span> ) || $response == ''<\/span>)\n     {\n      $results ['count'<\/span>] = 0<\/span>;\n      $results ['status'<\/span>] = 'Failure'<\/span>;\n      $results ['errorcode'<\/span>] = '999'<\/span>;\n      $results ['errorlink'<\/span>]  = 'https:\/\/jonrocket.com\/zencart\/errorcode-'<\/span> . $results ['errorcode'<\/span>];\n      $results ['errormessage'<\/span>] = 'HTTP Error'<\/span>;\n      \n      $message = $verb . ': '<\/span> . $results ['errormessage'<\/span>] . ' {<a href=\"'<\/span> . $results['errorlink'<\/span>] . '\">'<\/span> . $results ['errorcode'<\/span>] . '<\/a>)'<\/span>;\n      eBayLog($message, true<\/span>);\n\n      return<\/span> $results;\n     }\n      \n    $simpleXML = simplexml_load_string ( $response );\n\n    $results ['status'<\/span>] = ( string ) $simpleXML->Ack;\n\n    if<\/span> ($results ['status'<\/span>] != 'Success'<\/span>)\n     {\n      $results ['errors'<\/span>] = array<\/span> ();\n      foreach<\/span> ( $simpleXML->Errors as<\/span> $error )\n       {\n        $results ['errorcode'<\/span>] = ( string ) $error->ErrorCode;\n        $results ['errorlink'<\/span>]  = 'https:\/\/jonrocket.com\/zencart\/errorcode-'<\/span> . $results ['errorcode'<\/span>];\n        $results ['errormessage'<\/span>] = ( string ) $error->LongMessage;\n        \n        if<\/span> (!$suppressErrors) \n          {\n            $message = $verb . ': '<\/span> . htmlentities($error->LongMessage) . ' {<a href=\"'<\/span> . $results ['errorlink'<\/span>] . '\">'<\/span> . $error->ErrorCode . '<\/a>)'<\/span>;\n            eBayLog($message, true<\/span>);\n          }\n        \n        \n        $results ['errors'<\/span>] [] = array<\/span> (\n          'errorcode'<\/span> => ( string ) $error->ErrorCode,\n          'errormessage'<\/span> => $error->LongMessage,\n          'errorlink'<\/span> => $results['errorlink'<\/span>]\n        );\n       }\n      return<\/span> $results;\n     }\n\n    $results = $this<\/span>->addResults ( $simpleXML, $results );\n\n    return<\/span> $results;\n   }\n }\n \n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The code for a specific request is derived from the eBayRequest<\/strong> class.  For example, to get your recent eBay orders, a GetOrders<\/strong> request is made to eBay’s Trading API service.<\/p>\n\n\n
\/**\n *  GetOrders Request\n *  \n *  As a side-effect, executing this call will update the store\n *  quantities based on items sold on eBay.\n *\/<\/span>\nclass<\/span> eBayGetOrdersRequest<\/span> extends<\/span> eBayRequest<\/span>\n <\/span>{\n  var<\/span> $from;\n  var<\/span> $to;\n  var<\/span> $role;\n\n  function<\/span> __construct<\/span>($from, $to, $role)<\/span>\n   <\/span>{\n    $this<\/span>->from = eBayGetUTC8601 ( $from );\n    $this<\/span>->to = eBayGetUTC8601 ( $to );\n    $this<\/span>->role = $role;\n\n    parent<\/span>::__construct ( 'GetOrders'<\/span> );\n   }\n\n  protected<\/span> function<\/span> getXML<\/span>()<\/span>\n   <\/span>{\n    $authToken = ebayGetConfiguration ( 'AUTH_TOKEN'<\/span> );\n\n    $request = <<<XML\n    \n           <?xml version=\"1.0\" encoding=\"utf-8\" ?>\n           <GetOrdersRequest xmlns=\"urn:ebay:apis:eBLBaseComponents\">\n             <RequesterCredentials>\n                <eBayAuthToken>$authToken<\/span><\/eBayAuthToken>\n             <\/RequesterCredentials>\n             <CreateTimeFrom>{$this->from}<\/span><\/CreateTimeFrom>\n             <CreateTimeTo>{$this->to}<\/span><\/CreateTimeTo>\n             <OrderRole>{$this->role}<\/span><\/OrderRole>\n             <OrderStatus>Completed<\/OrderStatus>\n             <DetailLevel>ReturnAll<\/DetailLevel>\n           <\/GetOrdersRequest>\n    \nXML;<\/span>\n\n    return<\/span> $request;\n   }\n\n  function<\/span> addResults<\/span>($simpleXML, $results)<\/span>\n   <\/span>{\n    $results ['orders'<\/span>] = array<\/span> ();\n    foreach<\/span> ( $simpleXML->OrderArray->Order as<\/span> $order )\n     {\n      $result = array<\/span> ();\n      $result ['orderid'<\/span>] = ( string ) $order->OrderID;\n      $result ['subtotal'<\/span>] = floatval ( ( string ) $order->Subtotal );\n      $result ['total'<\/span>] = floatval ( ( string ) $order->Total );\n      $result ['buyerid'<\/span>] = ( string ) $order->BuyerUserID;\n      $result ['paidtime'<\/span>] = date_create ( ( string ) $order->PaidTime );\n      $results ['orders'<\/span>] [] = $result;\n      foreach<\/span> ( $order->TransactionArray->Transaction as<\/span> $transaction )\n       {\n         $itemId = $transaction->Item->ItemID;\n         $quantity = $transaction->QuantityPurchased;\n         $transactionId = $transaction->TransactionID;\n         eBayProcessItemSold($itemId, $transactionId, $quantity);\n       }\n     }\n    $results ['count'<\/span>] = count ( $results ['orders'<\/span>] );\n\n    return<\/span> $results;\n   }\n }\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The XML is sent to eBay’s server using the HTTP protocol.  The eBay server returns a response in XML.  The GetOrdersRequest<\/strong> class parses the returned XML to get information about the orders.<\/p>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Integration with eBay is made possible by the eBay Application Program Interface (API) which is a collection of services that expose methods that can be called from your server to access information and to define notifications to be sent by eBay to your server. What this means is that the eBay Integration plug-in for Zen […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[4,5],"class_list":["post-33","post","type-post","status-publish","format-standard","hentry","category-ebay-integration","tag-ebay","tag-ebay-integration"],"_links":{"self":[{"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/posts\/33","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/comments?post=33"}],"version-history":[{"count":9,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/posts\/33\/revisions"}],"predecessor-version":[{"id":53,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/posts\/33\/revisions\/53"}],"wp:attachment":[{"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/media?parent=33"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/categories?post=33"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/jonrocket.com\/zencart\/wp-json\/wp\/v2\/tags?post=33"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
The GetOrders<\/strong> request, like all of the eBay requests starts with creating XML<\/a> which contains the information to send to eBay’s server. This includes the three IDs used as keys and the authorization token allowing access to the eBay store information. <\/p>\n\n\n\n