Backend
API settings
API request
All APIs receive requests that always contain the following fields:
In addition, if the language could be determined, the request additionally gets the "lang" field (the language code). First the "data-lurazon-lang" attribute on the tag in which the catalog is generated is checked (see the Template render section), and only if it is not set - the "lang" attribute of the page's root "html" tag. If no value is found - the "lang" field is not passed:
In this case the "lang" field contains:
In the code examples below (as well as in the examples of backend requests and responses further in the documentation) the same identifiers repeat - this is intentional, to show that the same filters, options and entities are meant in different examples:
"FilterVehicleType" - the "Vehicle type" filter (type "Checkboxes")
"OptionSUV" - the "SUV" option of the "Vehicle type" filter
"FilterBrand" - the "Brand" filter (type "Radio buttons")
"OptionAudi" - the "Audi" option of the "Brand" filter
"FilterPrice" - the "Price" filter (type "Numeric")
"new" - the "Newest" sorting option
"12" - the "12 products" option of the number of shown results
Settings API
If the "Options API" field is filled in the template, this API must be created on the same domain and at the same path as specified in the field. This API must use the POST method
API request
This API receives requests with the following keys - by them the backend decides which page it answers for:
"template" - the template's identifier
"domain" - the domain of the page the template is built on
"path" - the page's path: the site's routes are not used with a custom API, so this is what the custom routing works by
"lang" - the identifier of the page's language, passed only on a multilingual site when the page's language is one of the site's languages
API response
This API must respond with the following fields, as needed:
"filters" - an ordered array of filters, each filter of the array must be a dictionary containing the following keys:
"id" - a required field, specifies the identifier of the filter's field (its key in "fields"), must be passed as a string value
"type" - a required field, specifies the filter's type, must be passed as a string value and be one of the values listed below:
"c" - the "Checkboxes" filter type
"r" - the "Radio buttons" filter type
"n" - the "Numeric" filter type
"fields" - the dictionary of the fields the page uses: the fields of the filters and the selector fields the "Object field: Selectors" elements show. Its keys are the fields' identifiers, each field must be a dictionary containing the following keys:
"label" - a required field for the field of a filter, specifies the filter's label, must be passed as a string value
"key" - an optional field, specifies the field's unique key, used instead of the identifier in the link and only for filters of the types: "Checkboxes" and "Radio buttons". Must be passed as a string value
"range" - an optional field, used only for filters of the type "Numeric", specifies the lowest and the highest value of the filter, must be passed as an array of two numbers. When passed, the filter's range slider takes them at once and they are not requested separately
"dependField" and "dependOption" - optional fields, make the field's filter dependent: it carries the "Filter unavailable" state until the filter of the field "dependField" has the option "dependOption" chosen (or one nested in it). Must be passed as string values. When that field is not a filter of the page, the dependency is ignored
"options" - an optional field, specifies all options of this field, used for filters of the types: "Checkboxes" and "Radio buttons" and for the "Object field: Selectors" elements. Must be passed as an ordered array of the field's options, each option of the array must be a dictionary containing the following keys:
"id" - a required field, specifies the option's identifier, unique for this field, must be passed as a string value
"label" - a required field, specifies the option's label, must be passed as a string value
"key" - an optional field, specifies the option's unique key, used instead of the identifier in the link, must be passed as a string value
"children" - an optional field, specifies the child options, used only for filters of the type: "Checkboxes" and for the "Object field: Selectors" elements. Must be passed as an ordered array of options
"sort" - the sorting settings dictionary, containing the following keys:
"options" - a required field, specifies all sorting options, must be passed as an ordered array of options, each option of the array must be a dictionary containing the following keys:
"id" - a required field, specifies the sorting option's unique identifier, must be passed as a string value
"label" - a required field, specifies the option's label, must be passed as a string value
"limit" - the settings dictionary of the number of shown results per page, containing the following keys:
"options" - a required field, specifies all options for limiting the number of shown results, must be passed as an ordered array of options, each option of the array must be a dictionary containing the following keys:
"id" - a required field, specifies the unique identifier of the option limiting the number of shown results, an integer must be passed as a string value
"label" - a required field, specifies the option's label, must be passed as a string value
Results API
If the "Results API" field is filled in the template, this API must be created on the same domain and at the same path as specified in the field. This API must use the POST method
API request
This API receives requests that additionally contain the "results" dictionary with the following keys:
"fields" - an array of the keys of the values that must be calculated and returned
"numbers" - the request requires returning the value ranges for filters of the "Numeric" type. The list of the identifiers of the filters for which the value ranges must be calculated and returned is passed in "filtersNumbers"
"facets" - the request requires returning the facets for filters of the "Checkboxes" and "Radio buttons" types. The list of the identifiers of the filters for which the facets must be calculated and returned is passed in "filtersFacets"
"objects" - the request requires returning the search results, taking into account the filter values passed via the keys: "valueSearch", "valueFilters", "valueSort", "valuePage", "valueLimit"
"count" - the request requires returning the number of search results, taking into account the filter values passed via the keys: "valueSearch", "valueFilters", "valueSort", "valuePage", "valueLimit"
"filtersNumbers" - an array of the identifiers of the filters of the "Numeric" type for which the ranges of possible values need to be returned
"filtersFacets" - an array of the identifiers of the filters of the "Checkboxes" and "Radio buttons" types for whose options the facets need to be returned
"valueSearch" - the string value of the template's search box, may be empty
"valueFilters" - a dictionary each key of which is a filter identifier with a value specific to the corresponding filter type. An example of the values passed for the corresponding filter types can be obtained with the functions: "filtersApplied" and "filtersCurrent" on the frontend
"valueSort" - a string value that is the identifier of a sorting option. This value is passed only when sorting has been applied for the template
"valuePage" - a numeric value that is the page the user is on. This value is passed only when limiting the number of shown results has been applied for the template
"valueLimit" - a numeric value that is the identifier of an option of the number of shown results. This value is passed only when limiting the number of shown results has been applied for the template
API response
When a request arrives at this endpoint, the template expects to receive in response only what is passed in the "results.fields" array. If this array contains only "count", then "{ count: ... }" must be returned, if "objects" and "count" then: { objects: ... , count: ... } and so on
Objects management
The following endpoints are used for adding and deleting objects via the API. It is convenient when an entity on the site is updated or deleted and needs to be sent to Lurazon for synchronization right away
Authorization
To pass data to the following APIs successfully, a correct request must be built and authorized via a JWT encoded with the "HS256" algorithm
The request must contain the following data:
"site" - the site's identifier
"token" - the authorization JWT
"list" - an array with the data needed by the API, which must not be empty and must hold no more than 1000 items. The whole request body must not exceed 16 MB - send a larger number of objects in several requests
The authorization JWT must encode a dictionary containing the keys: "type" with the value "objects" and "site" with the value of the site's identifier. The token's expiration ("exp") is required and must be no more than 3600 seconds ahead, otherwise the token is rejected. We recommend about 15 seconds
Add/update API
Send POST requests to https://objects.lurazon.com/set
To create or update objects, their list must be added to the "list" array. Each object must be a dictionary containing the keys:
"id" - a required string value that is the entity's unique identifier
"fields" - a required dictionary, each key of which is the identifier of a field registered in the site's cabinet. The value of each key is a dictionary containing the following keys:
"value" - the value of this field, which must be passed in the corresponding format:
For the "API selector" and "Multi selector" field types - an array of string values of option identifiers. For "Multi selector" only those saved in the cabinet must be passed
For the "Single selector" field type - a string value of an option identifier saved in the cabinet as one of the options
For the "String" and "Textarea" field types - a string value
For the "Number" field type - a numeric value
For the "Date" field type - a string value containing a date, best in the ISO 8601 format (a time zone offset in it is taken into account), or a timestamp in milliseconds. The date is stored in the UTC time zone. A date with a time but without a time zone is read as UTC, so pass the zone ("Z" or an offset) for exact results. A value that cannot be read as a date is not saved
For the "Image" field type - an array of string values that are links to images
"translations" - a dictionary with the field's translations, whose values are applied only to the fields for which translation is enabled in the cabinet. Each key is a language identifier set in the cabinet, and its value must be in the same format as the value for "value", which in turn is applied as the default translation
"unpublished" - an optional boolean value, if it equals 'true', the object is saved as unpublished
A request example (the field and option identifiers are the same as in the examples of the "API settings" section):
An object with an identifier that does not exist on the site yet is created, one with an existing identifier is fully overwritten. The response with the code 200 is a dictionary with the keys:
"required" - an array of the identifiers of the objects that were not saved: a missing or invalid value of a field with the "Required field" parameter
"failed" - an array of the identifiers of the objects that were not saved for any other reason (invalid "fields", the objects limit, a write error). An object without a valid identifier and a repeat of an identifier are only in "reasons"
"reasons" - a dictionary with the reasons why an object was not saved or was saved with remarks. The key is the object's position in the "list" array, starting from 0. The value is an array of entries in the "{ reason, field, language, value }" format, where "field", "language" and "value" are given only when they relate to the reason. Objects saved without remarks are not included. The possible values of "reason":
"id" - the object is not saved: its identifier is missing, not a string, empty, longer than 64 characters or contains a space
"duplicate" - the object is not saved: its identifier already came earlier in this "list" (the earlier one is processed)
"fields" - the object is not saved: "fields" is not a dictionary
"required" - the object is not saved: the required field "field" is missing or its value is invalid (every such field is listed)
"limit" - the object is not saved: the trial period's objects limit
"write" - the object is not saved: a write error
"skipped" - the object is saved, a part of it is left out: the value of the field "field" is invalid. With "language" - only that translation (unknown language, not a string, too long). With "value" - only that item of a list value (not an option of the field, not a valid key). A value "null" leaves a field empty on purpose and is not reported
"translations" - the object is saved without the translations of the field "field": "translations" is not a dictionary or the field is not translatable
"unknown" - the object is saved, the field "field" is ignored: there is no such field to write (not in the structure, or a system one the API does not set)
"unpublished" - the object is saved as published: "unpublished" is not a boolean
The code 400 - an invalid request body (one of the required keys is missing or the "list" array is empty or longer than 1000 items). The code 413 - the request body is larger than 16 MB. The code 403 - an invalid JWT or site identifier. The code 403 with the body "blocked" - the site is blocked (an unpaid invoice or deletion), objects are not accepted
Delete API
Send POST requests to https://objects.lurazon.com/del
To delete objects, the list of their identifiers must be added to the "list" array - the string values of "id" passed when adding:
Identifiers that do not exist on the site are ignored. The response with the code 200 is a dictionary with the "failed" key - an array of the identifiers of the objects that were not deleted because of a write error. The codes 400, 413 and 403 - as in the add/update API