Platform API Endpoints: Import Organisation Data Images and Files
Within the SQUIZZ.com Application Programming Interface (API) it contains endpoints that allows one organisation using 3rd party software to import and store images in the SQUIZZ.com platform, for different kinds of associated data. This associated data could be products, categories or category trees. The "Import Organisation Data Image" endpoints can be used to automate a number of processes, including the sharing of image data between different organisations, and regularly keeping organisation data up to date. The data imported into the platform will be hosted on the platforms servers, and then be available to be shared with connected organisations and people, if given permission.
To use the API endpoint you will need to have knowledge in building software applications, and how to make requests over the internet to call RESTful web services, which the platform's API endpoint is based on.
Topics |
Prerequisites
Before reading on please ensure that you have understood the following topics:
Web Service Endpoint: Import Organisation Product Image
This endpoint allows a product image file to uploaded and imported against an organisation's product. Once imported tthe image can then be shown in places where product is shown within the SQUIZZ.com platform, including in product listings, within the Product Detail page, on the Basket Details page, in the Order Checkout page, and other locations. By having one or more images set for products makes it possible for people to understand how a product looks, increasing the chances of purhases and sales of products.
This endpoint depends upon products previously been imported against an organisation using the Import Organisation Data endpoint. Once a product exists against an organisation up to 5 images can be imported against it. One of those images can be set as the primary image of the product, and will shown by default in places where the product appears. The first image imported against a product will be set as the primary image by default, but any of the 5 can be set as the primary image. If a primary image is deleted then the next image with the lowest ordering field value will become the primary image.
For each image being imported through this API once the image passes validation checks it will be placed onto a transaction holding area. Up to 100 images may be placed into a single transaction. Upon when the last/100th image is uploaded using this endpoint it can be set to commit the transaction, this will cause all the images in the holding area to be committed against the products after trading tokens costs have been covered by the organisation. By uploading images in batch it reduces the amount of trading token transactions needing to occur, and reduces server resources. When a session is created or validated a successful endpoint response will return a transaction ID required for this endpoint to allow an image to upload. Once a images transaction has successfully committed, the transaction ID will change. The response of this endpoint will return the new transaction ID used to upload the next batch of 100 images.
The image being imported using this endpoint must be placed into the Body of the HTTP request within a multi-part form. The image must be either a PNG. GIF or JPEG file type, containing either a png, gif, giff, jpeg, or jpg extension. If it's a JPEG image then it must be saved in the RGB colour profile. Avoid uploading animated GIFs since only its first frame will be looked at, and may not appear as expected. The image uploaded must be under 2MB in size. If your images are above 2MB in size then we recommend using the SQUIZZ.com Connector software to manage images since it's Product Images data export can automatically resize images upon calling this endpoint.
Note that there are trading token costs to import the product image using this API endpoint, of which the organisation importing the data must have enough tokens to allow the image to import. See the Trading Tokens and Pricing Help page for data import costs.
HTTP Request
HTTP Method | POST | |||
HTTP URL | https://api.squizz.com/rest/1/org/org/import_product_image/[session_id] | |||
Headers | ||||
---|---|---|---|---|
Content-Type | multipart/form-data | |||
Body Parameters | Data Type | Mandatory | Default Value | Description |
upload_file | BINARY | Yes | binary data of the image file. | |
key_product_id | STRING | Yes | Key identifier of the product that the image is to be assigned against. | |
key_image_id | STRING | Yes | Key identifier of the image that is unique from all other product images. | |
product_image_transaction_id | STRING | Yes | ID of the product image transaction that places the image in the same batch as other images with the same transaction ID. | |
commit_image_uploads | ENUM (Y or N) | No | N | If set to Y then the current image being uploaded and all other previously uploaded with the same transaction will be committed and applied against the products they are set to be assigned to. |
is_primary | ENUM (Y or N) | No | N | If set to Y - Yes, then the image will be set as the primary image used to identify the product. Note that if no other images are assigned to the same product then by default the image will be set as the primary. If another image is set as the primary then lose its primary status. |
title | STRING | No | Title of the image that labels the overall name of the image. | |
description | STRING | No | Description of the image that provides more information about the details of the image or associated characteristics. | |
ordering | INTEGER | No | 0 | Number that controls how the image is sorted when displayed within a list of other images assigned to the same product. The lower the number the higher it is placed in the list. |
HTTP Request Raw Example:
POST https://api.squizz.com/rest/1/org/import_product_image/EG30432823ABJFDS23332 HTTP/1.1
Host: api.squizz.com
Content-Length: 115
Content-Type: multipart/form-data
org_id=039583957203259WER2484832&api_org_key=12345678901234567890&api_org_pw=exmample_api_password&create_session=Y
HTTP Response
Response Data Type | JSON | |
Parameters | Data Type | Description |
---|---|---|
resultStatus | INTEGER |
|
configs.result | ENUM (SUCCESS or FAILURE) | Either "SUCCESS" or "FAILURE". If successful then a API session was successfully created. |
configs.result_code | STRING |
Status code of trying to import the product image. The following codes could be returned:
|
configs.images_committed_count | INTEGER | Number of image records that were successfully committed in the one transaction against their products. This will be set to 0 unless the commit_image_uploads request parameter is to Y, and one or more images is successfully committed. |
configs.product_image_upload_transaction_id | STRING | ID of either the current "product_image_upload_transaction_id", or if the commit_image_uploads request parameter is to Y, and one or more images is successfully committed in the same transaction, then this will contain the new transaction ID required for the next set of product images uploaded. |
configs.api_version | STRING | Version of the API being used to handle the endpoint request. |
HTTP Response Example:
"resultStatus": "1",
"version": "1.4",
"configs": {
"api_version": "1.0.0.0",
"result": "SUCCESS",
"result_code": "SERVER_SUCCESS",
"images_committed_count": 12,
"product_image_upload_transaction_id": "11EBD1E82B3826109F0B6AF3476460FC"
},
"message": ""
}
Web Service Endpoint: Import Organisation Category Image
This endpoint allows a category image file to uploaded and imported against an organisation's category. Once imported tthe image can then be shown in places where a category is shown within the SQUIZZ.com platform, including in category listings, and other locations. By having one or more images set for categories makes it easier for people to navigate through a category tree to find products, increasing the chances of purhases and sales of products.
This endpoint depends upon categories previously been imported against an organisation using the Import Organisation Data endpoint. Once a category exists against an organisation up to 5 images can be imported against it. One of those images can be set as the primary image of the category, and will shown by default in places where the category appears. The first image imported against a category will be set as the primary image by default, but any of the 5 can be set as the primary image. If a primary image is deleted then the next image with the lowest ordering field value will become the primary image.
For each image being imported through this API once the image passes validation checks it will be placed onto a transaction holding area. Up to 100 images may be placed into a single transaction. Upon when the last/100th image is uploaded using this endpoint it can be set to commit the transaction, this will cause all the images in the holding area to be committed against the categories after trading tokens costs have been covered by the organisation. By uploading images in batch it reduces the amount of trading token transactions needing to occur, and reduces server resources. When a session is created or validated a successful endpoint response will return a transaction ID required for this endpoint to allow an image to upload. Once a images transaction has successfully committed, the transaction ID will change. The response of this endpoint will return the new transaction ID used to upload the next batch of 100 images.
The image being imported using this endpoint must be placed into the Body of the HTTP request within a multi-part form. The image must be either a PNG. GIF or JPEG file type, containing either a png, gif, giff, jpeg, or jpg extension. If it's a JPEG image then it must be saved in the RGB colour profile. Avoid uploading animated GIFs since only its first frame will be looked at, and may not appear as expected. The image uploaded must be under 2MB in size. If your images are above 2MB in size then we recommend using the SQUIZZ.com Connector software to manage images since it's Category Images data export can automatically resize images upon calling this endpoint.
Note that there are trading token costs to import the category image using this API endpoint, of which the organisation importing the data must have enough tokens to allow the image to import. See the Trading Tokens and Pricing Help page for data import costs.
HTTP Request
HTTP Method | POST | |||
HTTP URL | https://api.squizz.com/rest/1/org/org/import_category_image/[session_id] | |||
Headers | ||||
---|---|---|---|---|
Content-Type | multipart/form-data | |||
Body Parameters | Data Type | Mandatory | Default Value | Description |
upload_file | BINARY | Yes | binary data of the image file. | |
key_category_id | STRING | Yes | Key identifier of the category that the image is to be assigned against. | |
key_image_id | STRING | Yes | Key identifier of the image that is unique from all other category images. | |
category_image_transaction_id | STRING | Yes | ID of the category image transaction that places the image in the same batch as other images with the same transaction ID. | |
commit_image_uploads | ENUM (Y or N) | No | N | If set to Y then the current image being uploaded and all other previously uploaded with the same transaction will be committed and applied against the categories they are set to be assigned to. |
is_primary | ENUM (Y or N) | No | N | If set to Y - Yes, then the image will be set as the primary image used to identify the category. Note that if no other images are assigned to the same category then by default the image will be set as the primary. If another image is set as the primary then lose its primary status. |
title | STRING | No | Title of the image that labels the overall name of the image. | |
description | STRING | No | Description of the image that provides more information about the details of the image or associated characteristics. | |
ordering | INTEGER | No | 0 | Number that controls how the image is sorted when displayed within a list of other images assigned to the same category. The lower the number the higher it is placed in the list. |
HTTP Request Raw Example:
POST https://api.squizz.com/rest/1/org/import_category_image/EG30432823ABJFDS23332 HTTP/1.1
Host: api.squizz.com
Content-Length: 115
Content-Type: multipart/form-data
org_id=039583957203259WER2484832&api_org_key=12345678901234567890&api_org_pw=exmample_api_password&create_session=Y
HTTP Response
Response Data Type | JSON | |
Parameters | Data Type | Description |
---|---|---|
resultStatus | INTEGER |
|
configs.result | ENUM (SUCCESS or FAILURE) | Either "SUCCESS" or "FAILURE". If successful then a API session was successfully created. |
configs.result_code | STRING |
Status code of trying to import the category image. The following codes could be returned:
|
configs.images_committed_count | INTEGER | Number of image records that were successfully committed in the one transaction against their categories. This will be set to 0 unless the commit_image_uploads request parameter is to Y, and one or more images is successfully committed. |
configs.category_image_upload_transaction_id | STRING | ID of either the current "category_image_upload_transaction_id", or if the commit_image_uploads request parameter is to Y, and one or more images is successfully committed in the same transaction, then this will contain the new transaction ID required for the next set of category images uploaded. |
configs.api_version | STRING | Version of the API being used to handle the endpoint request. |
HTTP Response Example:
"resultStatus": "1",
"version": "1.4",
"configs": {
"api_version": "1.0.0.0",
"result": "SUCCESS",
"result_code": "SERVER_SUCCESS",
"images_committed_count": 12,
"category_image_upload_transaction_id": "11EBD1E82B3826109F0B6AF3476460FC"
},
"message": ""
}