Impresee API for platform integrators
This document describes how you can integrate Impresee’s services into any e-commerce platform.
Basics
Impresee has released different services to allow the integration of our search engine into any e-commerce platform, and also to enable the creation of individual instances of the search engine for every different store. To access these services it is necessary to have an integrator api key. This key will be provided by Impresee. If you want to integrate our services into your platform you can request an api key sending us an email to support@impresee.com .
The services that are available to integrators are documented in detail below:
Create a store
The first step to integrate with impresee is to create an instance of the search engine for a store, for this you only need an integrator api key. The URL to create a store is the following:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/create_store/{integrator-api-key}
The above request corresponds to a POST, where the store data is sent through a json in the body, below is an example of a valid json.
The description of each parameter is documented below:
| Field | Type | Required | Description |
|---------------|--------|----------|-----------------------------------------|
| store_url | String | yes | store url |
| store_name | String | yes | store name |
| store_country | String | yes | store country |
| store_city | String | yes | store city |
| locale_code | String | yes | store language and territory identifier |
| timezone_code | String | yes | timezone code for the store |
| user_name | String | yes | store owner name |
| user_email | String | yes | store owner email |The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|----------------------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |
| store_key | String | Store key, if will be used to access the rest of the services of the store |It is critical to save the store-key in some database, because it will allow you to access the rest of the services.
Create the store catalog
Once a store has been created, it is necessary to create and update its catalog, this is done in three steps: create the catalog itself, register a webhook to update the js code with which the search engine will be displayed within the store, and finally refresh the catalog to download the product information and process the images.
The first step is then to create the catalog itself, which consists of registering the download and format information of the catalog, together with its product types. This service will return a url with the code that must be inserted in the store’s html header in order to use the search tools. The url of the service is:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/create_catalog/{integrator-api-key}/{store-key}
The above request corresponds to a POST, where the catalog data is sent through a json in the body, below is an example of a valid json.
The description of each parameter is documented below:
| Field | Type | Required | Description |
|----------------------|--------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| catalog_url_download | String | yes | Public url from which the catalog products can be downloaded. |
| catalog_format | string | no | Format in which the catalog products are stored in the previous url. Allowed values are: "xml_impresee_20" (default), "csv_impresee_10" , "json_impresee_20" |
| downloader_code | string | no | Catalog download algorithm, allowed values are: "download_url" (default), "samurai_paged" |
| catalog_market | string | no | Types of products in the catalog, the allowed values are "HOMEDECO" (default), "CLOTHES", "ALL", "OTHER". |The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|-------------------------------------------------------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |
| snippet_url | String | Url with the javascript code that must be inserted in the html header of the store, to use the search tools |It is important that the url of the snippet can change when there is a modification in the snippet configuration, so it should be possible to add and remove this url from the store html.
Register the snippet webhook
As mentioned above, every time a change is made to the integration settings (for example search by photo is disabled), a new snippet (javascript file) with the current configuration is generated and stored in our servers. When this new javascript file is generated, our system calls a webhook, which must be implemented to remove the previous javascript code and add the new code to the store html header.
To register the webhook to call the following url is used:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/register_snippet_webhook/{integrator-api-key}/{store-key}
The above request corresponds to a POST, where the catalog data is sent through a json in the body, below is an example of a valid json.
The description of each parameter is documented below:
| Field | Type | Required | Description |
|----------------|--------|----------|-------------------------------------------------------------------------------------------------------------------------|
| webhook_url | String | yes | Url to be called to register a new snippet for the store. For security reasons, we recommend adding an uuid to this url |The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|-------------------------------------------------------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |Once a webhook has been registered, it will be called every time there is a change in the browser configuration. This call will be a post request, with a field “snippet_url” containing the new snippet url. This url must be added to the store header, and the previous url must be removed.
Refresh the catalog
Once the catalog has been created and the webhook has been registered, the catalog must be refreshed. This process will download the catalog and process each product and its images so that they are available in the search engine. If it is the first time the catalog is refreshed, the download process will be slower, since each product must be processed.
The url to refresh the catalog is the following:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/refresh_catalog/{integrator-api-key}/{store-key}
The above request corresponds to a POST, where the catalog data is sent through a json in the body, below is an example of a valid json.
The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|-------------------------------------------------------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |Once a webhook has been registered, it will be called every time there is a change in the browser configuration. This call will be a post request, with a field “snippet_url” containing the new snippet url. This url must be added to the store header, and the previous url must be removed.
Register conversion events
Conversion events are triggered by purchases within a store. These events contain information about the purchased products, the transaction itself and the user who performed the transaction. The URL to register a conversion event is the following:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/conversion/{integrator-api-key}/{store-key}
The above request corresponds to a POST, where the event data is sent through a json in the body, below is an example of a valid json.
The description of each parameter is documented below:
| Field | Type | Required | Description |
|------------------------|---------------|----------|----------------------------------------------------------------|
| transaction_ip | String | yes | ip of the customer who made a purchase |
| transaction_user_agent | String | yes | user agent of the customer |
| transaction_id | String | no | unique id of the transaction, to avoid duplicate transactions |
| currency | String | no | three-letter ISO currency code. Example: “usd”, “clp” |
| total | float | no | total amount of the transaction, measured in the currency unit |
| discount | float | no | transaction discount, measured in the currency unit |
| shipping_cost | float | no | transaction discount measured in the currency unit |
| user | User | no | user data |
| products | Product array | yes | products purchased in the transaction |User
| Field | Type | Required | Description |
|---------|--------|----------|---------------------------|
| id | String | no | unique id of the customer |
| name | String | no | customer name |
| email | String | no | customer email |
| phone | String | no | customer phone |
| address | String | no | customer address |
| city | String | no | customer city |
| country | String | no | customer country |Product
| Field | Type | Required | Description |
|----------|--------|----------|------------------------------|
| id | String | yes | unique id of the product |
| price | String | yes | product price |
| quantity | String | yes | number of products purchased |
| sku | String | no | product sku |
| name | String | no | product name |
| category | String | no | product category name |The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|---------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |Login into the Impresee Console
In order for store owners to see their search metrics, configure their tool, and sign up for a plan, they need to sign up in the Impresee Console. For this, we let the following api available, which returns a url with a login token, with which the store owner can login directly into our system.
The url to request a login token is the following:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/store_signup_request/{integrator-api-key}/{store-key}
The above request corresponds to a POST. In addition, for security reasons you must send certain information about the user who is requesting the token:
Each parameter is described below
| Field | Type | Required | Description |
|-------------|--------|----------|--------------------------------------------------------------|
| user_agent | String | no | user agent of the store owner who requested the signup token |
| remote_ip | string | yes | ip of the store owner who requested the signup token |The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|---------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |
| url | String | Url with the token, with which the store owner must log in |Once this url is generated, it can be put into an <a href={url}> element inside the store owner admin page.
Delete a store
If a user decides to uninstall Impresee in his store, the script tag should be removed from the header of his page, and the following service must be called:
POST
https://api.impresee.com/ImpreseeAdmin/api/integrators/v1/delete_store/{integrator-api-key}/{store-key}
The server will return status 200 with the following json:
| Field | Type | Description |
|---------------|--------|---------------------------------------------------------------|
| status | int | 0: success, 1: error |
| error_message | String | If status=1, a message with the error description |