integration_documentation:request

integration_documentation:request

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
integration_documentation:request [2018/05/30 16:39]
markus [The request parameters in detail]
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[]''​
     * ''​order''​     * ''​order''​
     * ''​properties[]''​     * ''​properties[]''​
-  ​* **[[#​limiting_paging_parameters|Restriction / paging parameters]]**+    * ''​outputAttrib[]''​ 
 +    * ''​pushAttrib[][]''​ 
 +  ​* **[[integration_documentation:​parameters#​limiting_paging_parameters|Restriction / paging parameters]]**
     * ''​count''​     * ''​count''​
     * ''​first''​     * ''​first''​
Line 50: 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]''​ | Minimum value of a constant attribute. | 
-| ''​order''​ | Sorting of the results [[#Values of the ''​order''​ parameter|see below]]. | 
-| ''​properties[]''​ | Name of the [[export_patterns:​csv#​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). | 
- 
-\\  
- 
-=== Values of the ''​order''​ parameter === 
- 
-No value can be set as a default. 
- 
-^ Value ^ Description ^ Frontend response ^ 
-| ''<​empty>''​((Alternately,​ the ''​rank''​ value can also be given or the ''​order''​ parameter completely omitted)) | Relevance calculated by FINDOLOGIC | Best hits | 
-| ''​price ASC''​ | Most inexpensive products first | Most inexpensive first | 
-| ''​label ASC''​ | Alphabetic sorting | A-Z | 
-| ''​salesfrequency DESC''​ | Sales rank / most-sold items | Top sellers first | 
-| ''​dateadded DESC''​ | Newest products | New products first  | 
- 
-\\  
- 
-=== 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: [[export_patterns:​xml#​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. 
- 
----- 
  
 ==== Generating the request URL ==== ==== Generating the request URL ====