ebay-api
    TypeScript icon, indicating that this package has built-in type declarations

    7.0.2 • Public • Published

    eBay Node API in TypeScript with Browser support

    Build Status codecov

    GitHub GitHub release npm version npm

    This eBay API implements both Traditional (xml) and the RESTful eBay API. It supports client credentials grant and authorization code grant (Auth'N'Auth, OAuth2 and IAF).

    eBay Docs

    Changelog

    • v7.0.2 is the latest release.
    • See here for the full changelog.

    Implementation status

    RESTful API

    API Implemented
    Buy API Browse API v1.10.0
    Deal API v1.3.0
    Feed API
    Marketing API
    Offer API
    Order API
    Marketplace Insights API
    Commerce API Catalog API
    Charity API v1.2.0
    Identity API
    Notification API v1.2.0
    Taxonomy API v1.0.0
    Translation API v1_beta.1.4
    Developer API Analytics API
    Post Order API Cancellation API
    Case Management API
    Inquiry API
    Return API
    Sell API Account API v1.6.3
    Analytics API v1.3.0
    Compliance API v1.4.1
    Feed API
    Finance API v1.9.0
    Fulfillment API v1.19.10
    Inventory API v1.14.0
    Listing API
    Logistics API
    Marketing API v1.10.0
    Metadata API
    Negotiation API v1.1.0
    Recommendation API v1.1.0

    Traditional API

    API Implemented
    Finding API
    Shopping API
    Merchandising API
    Trading API
    Client Alerts API
    Feedback API

    Install

    npm install ebay-api 
    yarn add ebay-api

    🚀 Usage & Quick start

    Sign up for an API key here: Developer Account. Checkout API examples.

    NodeJS

    import eBayApi from 'ebay-api';
    // or:
    // const eBayApi = require('ebay-api')
    
    const eBay = new eBayApi({
      appId: '-- also called Client ID --',
      certId: '-- also called Client Secret --',
      sandbox: false
    });
    
    const item = await eBay.buy.browse.getItem('v1|254188828753|0');
    console.log(JSON.stringify(item, null, 2));

    Detailed configuration example

    import eBayApi from 'ebay-api';
    
    const eBay = new eBayApi({
      appId: '-- also called Client ID --',
      certId: '-- also called Client Secret --',
      sandbox: false,
    
      siteId: eBayApi.SiteId.EBAY_US, // required for traditional APIs, see https://developer.ebay.com/DevZone/merchandising/docs/Concepts/SiteIDToGlobalID.html
      
      marketplaceId:  eBayApi.MarketplaceId.EBAY_US, // defautl. required for RESTful APIs
      acceptLanguage: eBayApi.Locale.en_US, // defautl
      contentLanguage: eBayApi.ContentLanguage.en_US, // defautl.
    
      // optional parameters, should be omitted if not used
      devId: '-- devId --', // required for traditional Trading API
      ruName: '-- eBay Redirect URL name --', // 'RuName' (eBay Redirect URL name) required for authorization code grant
      
      authToken: '--  Auth\'n\'Auth for traditional API (used by trading) --', // can be set to use traditional API without code grant
    });

    Browser

    Check out live example: https://hendt.github.io/ebay-api/. Because of the eBay CORS problems a Proxy server is required to use the API in the Browser.

    For testing purpose you can use https://ebay.hendt.workers.dev/ url as proxy. You can also set up your own Proxy server. We have added a example for cloudfront workers: https://github.com/hendt/ebay-api/blob/master/proxy/worker.js

    Or use [https://github.com/Rob--W/cors-anywhere](CORS Anywhere is a NodeJS proxy) (works very well with heroku.com).

    <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/ebay-api@latest/lib/ebay-api.min.js"></script>
    <script>
      const eBay = new eBayApi({
        appId: 'appId',
        certId: 'certId',
        sandbox: false
      });
    
      // eBay.req.instance is AxiosInstance per default
      eBay.req.instance.interceptors.request.use((request) => {
          // Add Proxy
          request.url = 'https://ebay.hendt.workers.dev/' + request.url;
          return request;
      });
    
      eBay.buy.browse.getItem('v1|254188828753|0').then(item => {
          console.log(JSON.stringify(item, null, 2));
      }).catch(e => {
          console.error(e);
      });
    </script>

    🔧 eBayApi Config

    The first (required) parameter in eBayApi instance takes an object with following properties:

    Name Occurrence Description
    appId Required App ID (Client ID) from Application Keys.
    certId Required Cert ID (Client Secret) from Application Keys.
    devId Conditionally The Dev Id from Application Keys.
    sandbox Required
    Default: false
    If true, the Sandbox Environment will be used.
    ruName Conditionally The redirect_url value. More info.
    autoRefreshToken Required
    Default: true
    Auto refresh the token if it's expired.
    siteId
    Traditional
    Required
    Default: SiteId.EBAY_US
    eBay site to which you want to send the request (Trading API, Shopping API).
    authToken
    Traditional
    Optional The Auth'N'Auth token. The traditional authentication and authorization technology used by the eBay APIs.
    marketplaceId
    RESTful
    Required
    Default: MarketplaceId.EBAY_US
    Docs REST HTTP Header. X-EBAY-C-MARKETPLACE-ID identifies the user's business context and is specified using a marketplace ID value. Note that this header does not indicate a language preference or consumer location.
    scope
    RESTful
    Conditionally
    Default:
    ['https://api.ebay.com/oauth/api_scope']
    The scopes assigned to your application allow access to different API resources and functionality.
    endUserCtx
    RESTful
    Conditionally recommended
    RESTful
    Docs X-EBAY_C_ENDUSERCTX provides various types of information associated with the request.
    contentLanguage
    RESTful
    Conditionally required
    Default: ContentLanguage.en_US
    DocsContent-Language indicates the locale preferred by the client for the response.
    acceptLanguage
    RESTful
    Optional
    Default: Locale.en_US
    Docs Accept-Language indicates the natural language the client prefers for the response. This specifies the language the client wants to use when the field values provided in the request body are displayed to consumers.

    Load config from environment

    Use eBayApi.fromEnv() to load data from environment variables.

    Name Value
    appId process.env.EBAY_APP_ID
    certId process.env.EBAY_CERT_ID
    devId process.env.EBAY_DEV_ID
    authToken process.env.EBAY_AUTH_TOKEN
    siteId process.env.EBAY_SITE_ID
    marketplaceId process.env.EBAY_MARKETPLACE_ID
    ruName process.env.EBAY_RU_NAME
    sandbox process.env.EBAY_SANDBOX === 'true'

    🐞 Debug

    To see node debug logs use DEBUG=ebay:* environment variable.

    🔑 Access token types

    See the full Documentation here.

    Client credentials grant flow mints a new Application access token. Authorization code grant flow mints a new User access token.

    User access token (authorization code grant flow)

    👉 Recommended for all API Calls.

    You must employ a User token to call any interface that accesses or modifies data that is owned by the user (such as user information and account data). To get a User token, the users of your app must grant your application the permissions it needs to act upon their behalf. This process is called user consent. With the user consent flow, each User token contains the set of scopes for which the user has granted their permission (eBay Token Types).

    Application access token (client credentials grant flow)

    👉 Recommended for API calls that will only request application data (GET method, and it's also restricted).

    Application tokens are general-use tokens that give access to interfaces that return application data. For example, many GET requests require only an Application token for authorization. (eBay Token Types)

    If no other token is set, this token will be obtained automatically in the process of calling an RESTful API.

    Auth'N'Auth

    👉 The "old" way. Only works with Traditional API. Checkout the Auth'N'Auth example.

    You can also generate the token on eBay developer page and use it directly (see Detailed configuration example).

    OAuth2: Exchanging the authorization code for a User access token

    eBay Docs

    import eBayApi from 'ebay-api';
    
    // 1. Create new eBayApi instance and set the scope.
    const eBay = eBayApi.fromEnv();
    
    eBay.OAuth2.setScope([
      'https://api.ebay.com/oauth/api_scope',
      'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
      'https://api.ebay.com/oauth/api_scope/sell.fulfillment'
    ]);
    
    // 2. Generate and open Url and Grant Access
    const url = eBay.OAuth2.generateAuthUrl();
    console.log('Open URL', url);

    After you granted success, eBay will redirect you to your 'Auth accepted URL' and add a query parameter code

    Express example

    This is how it would look like if you use express:

    import eBayApi from 'ebay-api';
    
    app.get('/success', async function(req, res) {
      // 3. Get the parameter code that is placed as query parameter in redirected page
      const code = req.query.code; // this is provided from eBay
      const eBay = eBayApi.fromEnv(); // or use new eBayApi()
      
      try {
        const token = await eBay.OAuth2.getToken(code);
        eBay.OAuth2.setCredentials(token);
        // store this token e.g. to a session
        req.session.token = token
    
        // 5. Start using the API
        const orders = await eBay.sell.fulfillment.getOrders()
        res.send(orders);
      } catch(e) {
        console.error(e)
        res.sendStatus(400)
      }
    });

    If token is already in session:

    import eBayApi from 'ebay-api';
    
    app.get('/orders/:id', async function(req, res) {
      const id = req.params.id; 
      const eBay = eBayApi.fromEnv(); // or use new eBayApi(...)
      const token = req.session.token;
      if (!token) {
        return res.sendStatus(403);
      }
    
      eBay.OAuth2.setCredentials(token);
      
      // If token get's refreshed
      eBay.OAuth2.on('refreshAuthToken', (token) => {
        req.session.token = token;
      });
      
      try {
        // 5. Start using the API
        const order = await eBay.sell.fulfillment.getOrder(id);
        res.send(order);
      } catch(e) {
        console.error(e)
        res.sendStatus(400)
      }
    });

    RESTful API

    How to set the Scope

    const eBay = new eBayApi({
      // ...
      scope: ['https://api.ebay.com/oauth/api_scope']
    });
    
    // Or:
    eBay.OAuth2.setScope([
      'https://api.ebay.com/oauth/api_scope',
      'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
      'https://api.ebay.com/oauth/api_scope/sell.fulfillment'
    ]);

    Use apix.ebay.com or apiz.ebay.com (beta) endpoints

    For some APIs, eBay use a apix/apiz subdomain. To use these subdomains you can use .apix/.apiz before the api call like this:

      eBay.buy.browse.apix.getItem() // now it will use https://apix.ebay.com
      eBay.buy.browse.apiz.getItem() // now it will use https://apiz.ebay.com

    In any case eBay adds a new subdomain, it's also possible to configure whatever you want:

      eBay.buy.browse.api({subdomain: 'apiy'}).getItem() // now it will use https://apiy.ebay.com

    Change RESTful API call config

      eBay.buy.browse.api({
        returnResponse: true, // return the response instead of data
      }).getItem();

    How to refresh the token

    If autoRefreshToken is set to true (default value) the token will be automatically refreshed when eBay response with invalid access token error.

    Use Event Emitter to get the token when it gets successfully refreshed.

    eBay.OAuth2.on('refreshAuthToken', (token) => {
      console.log(token)
      // Store this token in DB
    });
    
    // for client token
    eBay.OAuth2.on('refreshClientToken', (token) => {
      console.log(token)
      // Store this token in DB
    });

    To manuel refresh the auth token use eBay.OAuth2.refreshAuthToken() and for the client token eBay.OAuth2.refreshClientToken(). Keep in mind that you need the 'refresh_token' value set.

    const token = await eBay.OAuth2.refreshToken();
    // will refresh Auth Token if set, otherwise the client token if set.

    Additional request headers

    Sometimes you want to add additional headers to the request like a GLOBAL-ID X-EBAY-SOA-GLOBAL-ID. You have multiple options to do this.

    RESTful API headers

      const eBay = new eBayApi();
    
      eBay.buy.browse.api({headers: {
          'X-EBAY-SOA-GLOBAL-ID': 'EBAY-DE'
      }}).getItem('v1|382282567190|651094235351').then((item) => {
        console.log(item)
      })

    Traditional API headers

    You can pass headers directly in the method call in the second parameter:

    eBay.trading.AddFixedPriceItem({
      Item: {
        Title: 'title',
        Description: {
          __cdata: '<div>test</div>'
        }
      }
    }, {
      headers: {
        'X-EBAY-SOA-GLOBAL-ID': 'EBAY-DE'
      }
    })

    Low level: use the Axios interceptor to manipulate the request

      import eBayApi from 'ebay-api';
      const eBay = new eBayApi(/* {  your config here } */);
    
      eBay.req.instance.interceptors.request.use((request) => {
        // Add Header
        request.headers['X-EBAY-SOA-GLOBAL-ID'] = 'EBAY-DE';
        return request;
      })

    Handle JSON GZIP response e.g fetchItemAspects

    You need a decompress library installed like zlib.

    npm install zlib # or yarn add zlib
      import eBayApi from 'ebay-api';
      import zlib from 'zlib';
    
      const toString = (data) => new Promise((resolve) => {
        zlib.gunzip(data, (err, output) => {
          if (err) throw err;
          resolve(output.toString());
        });
      });
    
      const eBay = new eBayApi(/* {  your config here } */);
    
      try {
        const data = await eBay.commerce.taxonomy.fetchItemAspects(/* categoryTreeId */);
        const result = await toString(data);
        
        console.log(result)
      } catch (e) {
        console.error(e);
      }

    Controlling Traditional XML request and response

    The second parameter in the traditional API has the following options:

    export type Options = {
      raw?: boolean // return raw XML
      parseOptions?: object // https://github.com/NaturalIntelligence/fast-xml-parser
      useIaf?: boolean // use IAF in header instead of Bearer
      headers?: Headers // additional Headers (key, value)
      hook?: (xml) => BodyHeaders // hook into the request to modify the body and headers
    };

    Fast XML is used to parse the XML. You can pass the parse option to parseOptions parameter.

    Examples

    Trading - AddFixedPriceItem (CDATA)

    You can submit your description using CDATA if you want to use HTML or XML.

    eBay.trading.AddFixedPriceItem({
      Item: {
        Title: 'title',
        Description: {
          __cdata: '<div>test</div>'
        }
      }
    })

    Trading - ReviseFixedPriceItem (Update the price of an item)

    eBay.trading.ReviseFixedPriceItem({
      Item: {
        ItemID: 'itemId',
        StartPrice: 'startPrice'
      }
    })

    Buy - getItem

    eBay.buy.browse.getItem('v1|382282567190|651094235351').then(a => {
        console.log(a);
    }).catch(e => {
        console.log(e)
    });

    Post-Order - getReturn

    eBay.postOrder.return.getReturn('5132021997').then(a => {
        console.log(a);
    }).catch(e => {
        console.log(e)
    });

    Finding - findItemsByProduct (use XML attributes and value)

    eBay.finding.findItemsByProduct({
      productId: {
        '@_type': 'ReferenceID',
        '#value': '53039031'
      }
    })
    
    // will produce:
    // <productId type="ReferenceID">53039031</productId>

    Finding - findItemsIneBayStores

    eBay.finding.findItemsIneBayStores({
        storeName: 'HENDT'
    }, {raw: true}).then(result => {
        // Return raw XML
        console.log(result);
    });

    Finding - findItemsAdvanced (findItemsByKeywords)

    eBay.finding.findItemsAdvanced({
        itemFilter: [{
            name: 'Seller',
            value: 'hendt_de'
        }],
        keywords: 'katze'
    }).then(result => {
        console.log(result);
    });

    Trading - GetMyeBaySelling

    eBay.trading.GetMyeBaySelling({
        SoldList: {
            Include: true,
            Pagination: {
                EntriesPerPage: 20,
                PageNumber: 1
            }
        }
    }).then(data => {
        console.log(data.results)
    });

    FAQ

    1. Do I need the eBay OAuth Client dependency?

    No. This library has already all authentication implemented and support also auto refreshing token.

    1. What does IAF mean?

    IAF stands for IDENTITY ASSERTION FRAMEWORK. The traditional API supports IAF. That means you can use the OAuth2 token with the traditional APIs.

    1. Is it possible to Upload Pictures directly to EPS?

    Yes. Checkout the Browser example and Node Example here.

    Contribution

    Check here

    Supported By

    hendt.de
    rootle.de

    📝 License

    MIT.

    Install

    npm i ebay-api

    DownloadsWeekly Downloads

    526

    Version

    7.0.2

    License

    MIT

    Unpacked Size

    1.82 MB

    Total Files

    191

    Last publish

    Collaborators

    • dantio