integration_documentation:request
Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
integration_documentation:request [2019/07/04 14:10] florian [Values of the ''order'' parameter] |
integration_documentation:request [2022/05/12 11:37] (current) florian [Service-URL] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ===== Request to FINDOLOGIC ===== | + | ===== Request to Findologic ===== |
- | In this article the request to FINDOLOGIC with all important parameters and information regarding the request is documented. \\ | + | In this article the request to Findologic with all important parameters and information regarding the request is documented. \\ |
If any questions occur, please contact our technical support [[support@findologic.com]]. | If any questions occur, please contact our technical support [[support@findologic.com]]. | ||
+ | |||
+ | <note tip>Our library helps requesting the Findologic API and also getting the data from the response and mapping it to corresponding objects. Read more at https://github.com/findologic/findologic-api </note> | ||
----- | ----- | ||
Line 8: | Line 10: | ||
==== Short overview ==== | ==== Short overview ==== | ||
- | * The FINDOLOGIC search service is only available after the first succeeded import. | + | * The Findologic search service is only available after the first succeeded import. |
- | * Queries are sent to FINDOLOGIC by means of HTTP requests. | + | * Queries are sent to Findologic by means of HTTP requests. |
* Before **each** actual query, a so-called //Alivetest// must be performed. | * Before **each** actual query, a so-called //Alivetest// must be performed. | ||
* The //Alivetest// returns either ''alive'' or ''dead''. If ''dead'' is the case, a fallback mechanism must take effect, and the conventional shop search must process the query. | * The //Alivetest// returns either ''alive'' or ''dead''. If ''dead'' is the case, a fallback mechanism must take effect, and the conventional shop search must process the query. | ||
Line 17: | Line 19: | ||
==== Fallback mechanism ==== | ==== Fallback mechanism ==== | ||
- | * Before each query, an //Alivetest// HTTP request is sent to FINDOLOGIC according to the following pattern: | + | * Before each query, an //Alivetest// HTTP request is sent to Findologic according to the following pattern: |
* ''%%http://service.findologic.com/ps/<SHOP_URL>/alivetest.php?shopkey=<SHOPKEY>%%''. | * ''%%http://service.findologic.com/ps/<SHOP_URL>/alivetest.php?shopkey=<SHOPKEY>%%''. | ||
- | * In the case of a response from ''alive'', the actual query is sent to the FINDOLOGIC service. | + | * In the case of a response from ''alive'', the actual query is sent to the Findologic service. |
- | * With all other responses other than ''alive'', the query is processed by the conventional shop search. \\ If the fallback mechanism is not working properly, the FINDOLOGIC search **may not** be used in a productive shop. | + | * With all other responses other than ''alive'', the query is processed by the conventional shop search. \\ If the fallback mechanism is not working properly, the Findologic search **may not** be used in a productive shop. |
* Also, a timeout of 1 second must be set for the //Alivetest//. If the response time exceeds 1 second, the query is processed by the conventional shop search. | * Also, a timeout of 1 second must be set for the //Alivetest//. If the response time exceeds 1 second, the query is processed by the conventional shop search. | ||
* A timeout of 3 seconds must be set for the actual query. If the response time exceeds 3 seconds, the query is processed by the conventional shop search. | * A timeout of 3 seconds must be set for the actual query. If the response time exceeds 3 seconds, the query is processed by the conventional shop search. | ||
Line 31: | Line 33: | ||
* **[[#service-url|Service-URL]]** | * **[[#service-url|Service-URL]]** | ||
- | * **[[#required_parameters|Required parameters]]** | + | * **[[integration_documentation:parameters#required_parameters|Required parameters]]** |
* ''shopkey'' | * ''shopkey'' | ||
* ''shopurl'' | * ''shopurl'' | ||
Line 37: | Line 39: | ||
* ''referer'' | * ''referer'' | ||
* ''revision'' | * ''revision'' | ||
- | * **[[#search_parameter|Search parameters]]** | + | * **[[integration_documentation:parameters#search_parameters|Search parameters]]** |
* ''query'' | * ''query'' | ||
* ''attrib[]'' | * ''attrib[]'' | ||
Line 44: | Line 46: | ||
* ''outputAttrib[]'' | * ''outputAttrib[]'' | ||
* ''pushAttrib[][]'' | * ''pushAttrib[][]'' | ||
- | * **[[#limiting_paging_parameters|Restriction / paging parameters]]** | + | * **[[integration_documentation:parameters#limiting_paging_parameters|Restriction / paging parameters]]** |
* ''count'' | * ''count'' | ||
* ''first'' | * ''first'' | ||
Line 52: | Line 54: | ||
---- | ---- | ||
- | ==== Service-URL ==== | ||
- | |||
- | The FINDOLOGIC search service must be addressed under the service URL. \\ | ||
- | You can find the URL in the customer account -> Account -> Master data. Or by clicking | ||
- | [[https://secure.findologic.com/login.symfony/web/app.php/shop/core|here]]. | ||
- | |||
- | ---- | ||
- | ==== The request parameters in detail ==== | ||
- | |||
- | \\ | ||
- | |||
- | ==== Required parameters ==== | ||
- | |||
- | ^ Parameter ^ Brief description ^ | ||
- | | ''shopkey'' | Identification number of the requesting shop, consisting of 32 hex digits (1-9/A-F). The shopkey can be found in the customer account -> Account -> Master data. | | ||
- | | ''shopurl'' | Absolute URL of the requesting shop (e.g. shop.de or sub.shop.de). | | ||
- | | ''userip'' | IP address of the searching user. This data is used for billing and for the user identifier. The data remains under lock and key! | | ||
- | | ''referer'' | The referer URL of the searching user. To track the search history. These data remain under lock and key! | | ||
- | | ''revision'' | Version of the shop plugin. It is used to identify the version of the plugin. | | ||
- | |||
- | \\ | ||
- | |||
- | ==== Search parameter ==== | ||
- | |||
- | ^ Parameter ^ Brief description ^ | ||
- | | ''query''| The searched query parameter. | | ||
- | | ''attrib[<name>][]((The array brackets [] must always be included after the attribute name.))'' | List of discrete attributes to be applied ((Discrete attributes can, as opposed to constant attributes, only take on certain values. E.g. Size=XL,L,M,...)) Filter | | ||
- | | ''attrib[<name>][min]'' | Minimum value of a constant attribute((constant attributes can, as opposed to discrete attributes, take on any numerical values. E.g. price)). | | ||
- | | ''attrib[<name>][max]'' | Maximum value of a constant attribute. | | ||
- | | ''order'' | Sorting of the results [[#Values of the ''order'' parameter|see below]]. | | ||
- | | ''properties[]'' | Name of the [[csv_export_documentation:csv_format#optional_additional_columns|additional optional export columns]], whose contents are to be output (only relevant for XML output). | | ||
- | | ''outputAttrib[]'' | Name of the attributes which may be available in the template (only relevant for Direct Integration). | | ||
- | | ''pushAttrib[<key>][<value>]'' | Name and value of the filter which should be pushed.| | ||
- | |||
- | \\ | ||
- | |||
- | ==== Values of the ''order'' parameter ==== | ||
- | |||
- | The values //dynamic// and //asc/desc// can be added to every value listed below, f.e.: //salesfrequency dynamic desc//. | ||
- | |||
- | The values //asc/desc// are specifying whether to sort the results ascending (asc) or descending (desc). | ||
- | |||
- | <note>The values //asc/desc// have to be transmitted in lowercase</note> | ||
- | |||
- | The value //dynamic// is calculating the specified value in a dynamic way and does not sort the results hard. This means that the textual relevance, the configured merchandising features and boosting via the personalization API is still influencing the sorting. | ||
- | |||
- | ^ Value ^ Description ^ | ||
- | | ''salesfrequency'' | Sort by sales rank / most-sold items. | | ||
- | | ''shopsort'' | Sort by the values, that are exported via the feed in the field [[xml_export_documentation:xml_format|//sort//]]. | | ||
- | | ''price'' | Sort by price. | | ||
- | | ''label'' | Alphabetic sorting. | | ||
- | | ''dateadded'' | Sort by date. | | ||
- | | ''<empty>'' or ''rank'' | Sort by default order, that was specified (If the default order is empty, the sort order will be textual relevance only). | | ||
- | |||
- | <note>We strongly advise our customers to use a dynamic calculation for the default order.</note> | ||
- | |||
- | |||
- | \\ | ||
- | |||
- | ==== Limiting / paging parameters ==== | ||
- | |||
- | ^ Parameter ^ Brief description ^ Default value ^ | ||
- | | ''count'' | Number of items to be displayed (page size - max. 32767, higher values will get set to this) | ''10'' | | ||
- | | ''first'' | First item to be displayed on the page, 0-based (**NOT** page number, but rather the index of the item, the page with the 1st item starts with 0, the page with the 2nd with 1, ''first=count'' indicates the second page; the page number is thus equal to ''first/count+1''). | ''0'' | | ||
- | | ''identifier'' | ID of an item, only this item is returned (''query'' is ignored) | ''null'' | | ||
- | | ''group[]((For XML export, the parameter must be "usergrouphash"; note the following: [[xml_export_documentation:xml_format#usergroups|Calculating the usergroup hash]]))'' | Customer groups to be searched ((Can be given multiple times; Only those items are displayed that are assigned to at least one of these customer groups; Groups that do not exist in the export are ignored.)) | empty list | | ||
- | |||
- | ---- | ||
- | |||
- | ==== Applying filters ==== | ||
- | |||
- | Filters of the query output are performed using the ''attrib'' parameter. | ||
- | |||
- | The name and value of the filter are case-sensitive. | ||
- | |||
- | \\ | ||
- | |||
- | === Category filter === | ||
- | |||
- | As a rule, the ''cat'' key is used for categories. | ||
- | <code javascript>attrib[cat][]=Men</code> | ||
- | |||
- | \\ | ||
- | |||
- | == Hierarchical categories == | ||
- | |||
- | Hierarchies are interlinked by means of underscores ("_") in accordance with the shop hierarchy. | ||
- | <code javascript>attrib[cat][]=Men_Trousers</code> | ||
- | |||
- | \\ | ||
- | |||
- | === Vendor filter === | ||
- | |||
- | As a rule, the ''vendor'' key is used for categories. | ||
- | <code javascript>attrib[vendor][]=FINDOLOGIC</code> | ||
- | |||
- | \\ | ||
- | |||
- | === Price filter === | ||
- | |||
- | The price range is limited by ''min'' and ''max'' values. | ||
- | <code javascript>attrib[price][min]=10.5&attrib[price][max]=200.0</code> | ||
- | |||
- | \\ | ||
- | |||
- | === Attribute filter === | ||
- | |||
- | If the ''color'' attribute is stored for shop items, a ''color'' filter can be applied as follows. | ||
- | <code javascript>attrib[color][]=red</code> | ||
- | |||
- | \\ | ||
- | |||
- | === Multiple values of one filter type === | ||
- | |||
- | Multiple values are (currently) "AND-ed" exclusively. This means that only those products are output that meet satisfy all filters in the event of multiple values for one filter type. | ||
- | <code javascript>attrib[color][]=red&attrib[color][]=blue</code> | ||
- | In the above example, only those products are output that are red **and** blue. | ||
- | |||
- | ---- | ||
- | |||
- | ==== Push attributes ==== | ||
- | |||
- | It is also possible to push products within the request. | ||
- | |||
- | The pushing is done with the help of the attributes and is performed by using the ''pushAttrib'' parameter. | ||
- | <note tip>Pushing attributes can be used for a personalized search.</note> | ||
- | <code javascript>pushAttrib[color][red]=3</code> | ||
- | |||
- | There can be more than one attribute pushed. | ||
- | <code javascript>pushAttrib[color][blue]=0.5&pushAttrib[gender][woman]=1.5</code> | ||
- | |||
- | More on this topic can be found [[:Personalization|in the manual for our personalization.]] | ||
- | \\ | ||
- | ---- | ||
==== Generating the request URL ==== | ==== Generating the request URL ==== |