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 Last revision Both sides next revision | ||
|
integration_documentation:request [2018/06/05 14:17] markus [Basic structure of the request] |
integration_documentation:request [2020/06/16 14:54] amil |
||
|---|---|---|---|
| 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 43: | Line 45: | ||
| * ''properties[]'' | * ''properties[]'' | ||
| * ''outputAttrib[]'' | * ''outputAttrib[]'' | ||
| - | * ''pushAttrib[<key>][<value>]'' | + | * ''pushAttrib[][]'' |
| - | * **[[#limiting_paging_parameters|Restriction / paging parameters]]** | + | * **[[integration_documentation:parameters#limiting_paging_parameters|Restriction / paging parameters]]** |
| * ''count'' | * ''count'' | ||
| * ''first'' | * ''first'' | ||
| Line 54: | Line 56: | ||
| ==== Service-URL ==== | ==== Service-URL ==== | ||
| - | The FINDOLOGIC search service must be addressed under the 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 | 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]]. | [[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. | ||
| - | |||
| - | ---- | ||
| - | |||
| - | ==== Push attributes ==== | ||
| - | |||
| - | It is also possible to push products within the request. This can be used for a personalized search. | ||
| - | |||
| - | This pushing is done with the help of the attributes and is performed by using the ''pushAttrib'' parameter. | ||
| - | |||
| - | <code javascript>pushAttrib[color][red]=3</code> | ||
| - | |||
| - | There can be more than one attribute pushed. | ||
| - | <code javascript>pushAttrib[cat][meat]=0.5&pushAttrib[diet][vegan]=1.5</code> | ||
| - | |||
| - | More on this topic can be found [[:Personalization|in the manual for our personalization.]] | ||
| - | |||
| - | \\ | ||
| ---- | ---- | ||