API Ceneo - AuthorizationService documentation - PartnerService

Table of contents:

    Site definition

    Name: PartnerService
    Purpose: Site for partners.
    Version: 1.0
    Protocol: REST, OData
    Address: https://partnerzyapi.ceneo.pl/PartnerService.svc
    Metadata: https://partnerzyapi.ceneo.pl/PartnerService.svc/$metadata
    Authorization: OAuth 2.0 protocol, 'client_credentials’ mode, Bearer token

    Version history

    Version number Description of changes Date
    2.0.0 New PartnerServiceV2.svc endpoint was added based on OData V3 protocol. We recommend using it. Extension of GetProducts method by optional parameters: lowestPrice, highestPrice and onlyBasketOffers. Products was extended by HasBasketOffers. 2013-02-07
    1.0.0 First service version 2012-07-23

    Glossary of terms

    REST Representational state transfer (REST) - a style of software architecture for services providing data in the form of resources. Individual resources are identified using a uniform resource identifier (URI).
    http://en.wikipedia.org/wiki/Representational_state_transfer
    URI Uniform Resource Locator - a uniform resource identifier on the Web.
    http://en.wikipedia.org/wiki/Uniform_Resource_Identifier,
    http://www.ietf.org/rfc/rfc3986.txt
    OData Open Data Protocol - a REST protocol dedicated for loading and updating data. It uses the ATOM standard and AtomPub protocol.
    http://www.odata.org/
    OAuth 2.0 Authorization protocol in HTTP services
    http://tools.ietf.org/html/draft-ietf-oauth-v2-22
    Atom Standard of data definition based on XML document.
    http://tools.ietf.org/html/rfc4287
    AtomPub Atom Publishing Protocol – information publishing standard in services, which is to replace RSS channels in the future.
    http://tools.ietf.org/html/rfc5023
    JSON JavaScript Object Notation – a text-based notation of data entry, based on the JavaScript language.
    http://en.wikipedia.org/wiki/JSON
    HTTP status codes HTTP queries always return a status code informing about operation result. Below you may find a link to the list of statuses:
    http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

    Site operations

    The site is a REST-based service providing resources using the OData protocol, allowing for performance of selected operations using the GET protocol. Data and access security is ensured by encrypted connection and use of the OAuth protocol for authorisation. The site automatically provides data on resources, data types and operations it contains. Errors are always return in an http reply header.
    The site can be accessed only by users of the Affiliate Program on Ceneo.

    Security

    Access to authorisation is secured with an SSL certificate and should be made using https. Access to data may be provided using non-encrypted http.

    Access to the site, its resources and operations needs to be authorised first using a special token (a string of characters) which is generated once for a specified period of time after which it expires. The token is of a single use, which means that after its expiry, it will be impossible to use it for authorisation.

    Note! An authorisation token cannot be downloaded using http, because it may compromise the API key.

    Authorization

    Access to each resource and operation is based on the OAuth 2.0 protocol and the client_credentials authorisation type. To connect to the site, the customer needs to download an access token first by providing an API key. The token is generated in the Basic authorisation mode using a special service, i.e. AuthorizationService.svc, and the GetToken method accepting the grant type as a parameter and requiring the API key to be sent in the GET https query header.

    Data to be sent in the header:
    Authorization: Basic api_key

    Sample call:
    URI
    /AuthorizationService.svc/GetToken?grantType='client_credentials'
    Header
    Authorization: Basic F7869662-F334-427C-94B9-2D876BFCD589

    In reply a customer receives a token in the header together with information on its type and validity time in seconds after which it will expire. The token type has always the “bearer” value.

    If any parameter is incorrect, the HTTP 400 BadRequest error will be returned together with a detailed message in accordance with the OAuth 2.0 specification.

    If a user has no rights to access the resources, the HTTP 401 Unauthorized error will be returned.

    Data to be read in the header:
    access_token: token
    expires_in: time_in_seconds
    token_type: token_type

    Sample response:
    access_token: 8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c.
    expires_in: 900
    token_type: bearer

    The token should be added to the header of each query for resources and performance of operation (except for loading a new token) in the following way: Authorization: Bearer token Sample header:
    Authorization: Bearer 8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c. It can also be added as URI parameter: /Categories?access_token=8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c.

    If the token has expired or the query is without any token, the HTTP 401 Unauthorized error is to be returned.

    Error handling

    HTTP error details are returned in the http header in three parameters (also compliant with OAuth 2.0): error: shortened error_code_–_string_of_characters
    error_description: short_description_–_string_of_characters,_optionally
    error_uri: address_to_webpage_with_detailed_description_–_string_of_characters,_optionally

    Site definition (metadata)

    The site provides metadata describing all available resources and operations as well as data types.
    Metadata is available at /Service_name.svc/$metadata

    To access it, no encrypted connection or authorization is required (it is possible to query using http).

    URI structure

    URI is defined using OData protocol.

    The resource access template is as follows: /Site_name.svc/Resource_name?$optional_parameters The operation call template is as follows: /Site_name.svc/Operation_name?optional_parameters

    Transmitting collections for operations

    Collections may be transmitted for operations only in Query String parameters in GET operations. A collection needs to be serialised to the JSON format.

    Query String encoding

    Query String parameters need to be encoded as UTF8. For example, in JavaScript this can be done using the encodeURIComponent function. Encoding is defined in the URI standard.

    Data format

    Data is returned by default as ATOM XML, but it is possible to request JSON format by adding the $format=json parameter.

    Sample: /Site_name.svc/Resource_name_or_Operation_name?optional_parameters&$format=json

    Data cache

    Results of queries for resources and operations (except for loading a token) are kept for 15 minutes, which means that during that time the same query will return the same data even though it could change. The data storage time may change.

    Limits of call number

    Quantitative limits may be imposed for queries for resources and operations (hourly, daily, etc.). Then, after the limit is exceeded, the HTTP 403 Forbidden error will be returned together with the error code and description informing that the number of calls has been exceeded.

    Available resources

    Products - Top products

    List of top products on Site.
    Available fields
    Name Type Description
    Id (KEY) Int32 Product ID
    Name String Name
    CategoryId Int32 Category ID
    LowestPrice Decimal Lowest price
    HighestPrice Decimal Highest price
    Shops Int32 Number of shops where product can be bought
    Rating Double Rating
    ProductReviews Int32 Number of reviews
    ManufacturerName String Manufacturer's name
    HasBasketOffers Boolean Are there any product offers on Buy on Ceneo?
    Popularity Int32 Popularity - Information on product popularity compared to other listed. The higher the number, the more popular the product.
    Categories IQueryable`1<Category> Category
    Url String Url address - You need to add a Partner ID yourself – see FAQ.
    ThumbnailUrl String Url address to thumbnail (below 245x224)
    MediumThumbnailUrl String Url address to thumbnail (below 140x110)
    SmallThumbnailUrl String Url address to thumbnail (below 75x75)

    Categories - Product categories

    List of product categories on Site.

    The category list shows all categories available on Ceneo, also those which cannot be used in the Affiliate Program. Use of a category and all of its subcategories is restricted if there is an IsRestricted flag set as true.

    The category list has 20 records on one page.

    Sample scenarios for downloading category data:

    • Category list sorted by name in ascending order /PartnerService.svc/Categories?orderby=Name asc
    • Single ID 40 category /PartnerService.svc/Categories(40)
    • Category list with child categories /PartnerService.svc/Categories?$expand=Categories Note! Maximum number of nesting levels in one query is 2.
    • Single ID 40 category with top products sorted by popularity in ascending order /PartnerService.svc/Categories(40)/Products?$orderby=Popularity desc
    Available fields
    Name Type Description
    Id (KEY) Int32 Category ID
    Name String Name
    ParentId Int32 ID of parent category - For the main category it is 0.
    IsRestricted Boolean Flag if category use is limited - Limited category (e.g. erotic) and their products cannot be used in the Affiliate Program.
    Path String Full path (breadcrumbs)
    Url String Url address - You need to add a Partner ID yourself – see FAQ.
    Categories IQueryable`1<Category> Child categories
    Products IQueryable`1<Product> Products - Top category products.

    Available operations

    GetProducts - Product search

    Product search by name. It searches by default only in non-restricted categories.

    Http method: GET
    Output parameter: IQueryable`1<Product>

    Input parameters
    Name Type Description
    searchText String Searched phrase
    categoryId Nullable`1<Int32> Category ID (optional)
    pageSize Nullable`1<Int32> Page size (optional)
    pageIndex Nullable`1<Int32> Page number (optional)
    includeRestricted Nullable`1<Boolean> Search also in restricted categories (optional, deactivated/false by default)
    lowestPrice Nullable`1<Decimal> Minimum product price (optional)
    highestPrice Nullable`1<Decimal> Maximum product price (optional)
    onlyBasketOffers Nullable`1<Boolean> Search only in offers on Buy on Site (optional, deactivated/false by default)
    Call
    /PartnerService.svc/GetProducts?searchText=x&categoryId=x&pageSize=x&pageIndex=x&includeRestricted=x&lowestPrice=x&highestPrice=x&onlyBasketOffers=x

    This method is used to search products by name and returns the same results as search on Ceneo

    Sample use scenarios:

    • Products with 'sony' in name /PartnerService.svc/GetProducts?searchtext='sony'
    • Products with 'sony' in name and sorted by popularity in descending order /PartnerService.svc/GetProducts?searchtext='sony'&$orderby=Popularity desc
    • Products with 'sony' in name and category information /PartnerService.svc/GetProducts?searchtext='sony'&$expand=Categories
    • Products with 'sony' in name from 'Mobile Phones' category /PartnerService.svc/GetProducts?searchtext='sony'&categoryId=471

    GetBooks - Book search

    Book search by ISBN, title and author. All parameters are required.

    Http method: GET
    Output parameter: IQueryable`1<Product>

    Input parameters
    Name Type Description
    title String Book title
    author String Book author
    isbn String Book ISBN
    Call
    /PartnerService.svc/GetBooks?title=x&author=x&isbn=x

    FAQ

    Frequently asked questions

    1. Why does this date has a strange format?

      The date format in XML is compliant with the ISO 8601 standard specification http://en.wikipedia.org/wiki/ISO_8601.
      In the JSON format, date is a millisecond number Date(1309874335920). The way on how to use is can be found at http://www.w3schools.com/jsref/jsref_obj_date.asp

    2. Why do Polish characters not display correctly in the JSON format?

      All national characters (including Polish) are in the Unicode format whose description can be found at http://en.wikipedia.org/wiki/List_of_Unicode_characters#Latin_Extended-A. For example, "ó" has the Unicode number U+00F3 which is shown as \u00f3 in json.

    3. Does Url for product and category contain a Partner ID?

      No, it doesn’t. You need to add #pid=[PARTNER ID]yourself, while [PARTNER ID] can be found in the Affiliate Program’s panel in Account Settings.
      For example, a correct product url is http://www.ceneo.pl/12454277#pid=5555

    4. I receive a 'bad_request' message when calling a GetProducts method.

      The site informs you that the method URI is incorrect. Perhaps you have missed one of obligatory parameters or transmitted it incorrectly.

    5. How to transmit a 'decimal' value through URI for GetProducts?

      Add an m suffix to the number, e.g./PartnerService.svc/GetProducts?searchtext='sony'&lowestPrice=500m&highestPrice=2000m.

    6. My client app cannot format a reply.

      You need to check the value of the Accept header sent to the site with each HTTP request. It should be the same as the value of the Content-Type header in server’s reply.

    7. How can I preview parameters of HTTP request and reply such as headers?

      Currently all web browsers offer tools for developers to check DOM of a page, debug a JavaScript code and monitor network traffic, e.g. Firebug for Firefox. You can also use free Fiddler.

    8. Are there any libraries for My Favourite Programming Language, which allow for convenient use of OData protocol?

      Yes, there are libraries for a few languages, which facilitate the use of OData: .NET Framework, JavaScript, Java, Ruby, PHP.