Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Functional Apps
Catalog Images app
Official extension
Version: 0.3.1
Latest version: 0.3.1

The Catalog Images app provides REST and GraphQL APIs for users to save or delete catalog images on File Manager without overriding images with the same name.

Installation

Using the VTEX IO CLI, log in to your desired account and workspace and run the following command to install the Catalog Images app:


_10
vtex install vtex.catalog-images@0.x

Once the installation is confirmed, you can use the Catalog Images app's resources through REST API or GraphQL as long as you follow the authentication process.

Authentication

First, you must have an appKey and appToken to use as authentication headers in this application’s requests. Read Authentication for more information on how to obtain these credentials.

Using your appKey and appToken, make the following API request to obtain a local token, which is required by the app. Replace {{accountName}} with your VTEX account name and {{my_appkey}} and {{my_apptoken}} with their respective values.

Request local token:


_10
curl --location --request POST 'http://api.vtexcommercestable.com.br/api/vtexid/apptoken/login?an={{accountName}}' \
_10
--header 'Content-Type: application/json' \
_10
--data-raw '{
_10
"appkey": "{{my_appkey}}",
_10
"apptoken": "{{my_apptoken}}"
_10
}'

Response:


_10
{
_10
"authStatus": "Success",
_10
"token": "{{local_token}}",
_10
"expires": 1673305329
_10
}

The token value you will receive as a response is required for authentication in the app's API calls, explained in the following sections.

REST API

There are two REST API endpoints available to manage images using the Catalog Images app:

Save image

To save an image in File Manager, use the request below. Make sure to send one image at a time and set the request body format to multipart/form-data.


_10
curl --location --request POST 'https://app.io.vtex.com/vtex.catalog-images/v0/{{accountName}}/{{workspace}}/images/save/{{fileName}}' \
_10
--header 'VtexIdclientAutCookie: {{token}}' \
_10
--form '=@"{{filePath}}"'

Make sure to replace the following values in your request:

PropertyLocationTypeDescriptionExample
accountNamePathStringName of the VTEX account.mystore
workspacePathStringName of the workspace where you want to upload the image.master
fileNamePathStringName and extension of the image file.product.png
tokenHeader (VtexIdClientAutCookie)-Local token required for authentication.-
filePathRequest bodyStringFull path of the file./C:/Images/product.png

If there is already an image with the same filename given, the response will be Conflict (409) with the conflicted image URL in the response body.

Otherwise, the response will be OK (200) with the id, slug, and fullUrl in the response body, as follows:

Response body example (200 OK):


_10
{
_10
"id": "special-offer.png",
_10
"slug": "/assets/vtex.catalog-images/products/special-offer___782206cd73597a717ed67eba399167a6.png",
_10
"fullUrl": "https://myvtexaccountname.vtexassets.com/assets/vtex.catalog-images/products/special-offer___782206cd73597a717ed67eba399167a6.png"
_10
}

Delete image

The following REST API route allows you to delete a Catalog image in File Manager:


_10
curl --location -g --request DELETE 'https://app.io.vtex.com/vtex.catalog-images/v0/{{accountName}}/{{workspace}}/images/save/{{fileName}}' \
_10
--header 'VtexIdclientAutCookie: {{token}}'

Replace the values as explained below:

PropertyLocationTypeDescriptionExample
accountNamePathStringName of the VTEX account.mystore
workspacePathStringName of the workspace where you want to upload the image.master
fileNamePathStringName and extension of the image file.product.png
tokenHeader (VtexIdClientAutCookie)-Local token required for authentication.-

If there is already an image with the same fileName given, the response will be Conflict (409) with the conflicted image URL in the response body.

If the image exists and is successfully deleted, the response will be an empty body with status code OK (200). If the image does not exist, the response will be Not Found (404).

GraphQL API

The following mutations are available for Catalog images using the app’s GraphQL API:

saveImage

Use the following mutation to save an image on File Manager using GraphQL:

Mutation:


_10
saveImage(filename: String!, file: Upload!){
_10
id
_10
slug
_10
fullUrl
_10
}

Response body example (200 OK):


_10
{
_10
"id": "special-offer.png",
_10
"slug": "/assets/vtex.catalog-images/products/special-offer___782206cd73597a717ed67eba399167a6.png",
_10
"fullUrl": "https://myvtexaccountname.vtexassets.com/assets/vtex.catalog-images/products/special-offer___782206cd73597a717ed67eba399167a6.png"
_10
}

If there is already an image with the same name registered on File Manager, the response will contain an array of errors, including CONFLICT_FILE_ERROR.

Response body example (409 Conflict):


_13
"errors": [
_13
{
_13
[...]
_13
"extensions": {
_13
"code": "CONFLICT_FILE_ERROR",
_13
"data": {
_13
"statusCode": 409,
_13
"file": "https://sandboxintegracao.vtexassets.com/assets/vtex.catalog-images/src/car22___aabd8ae86160533e7090c024ac004bc6.jpg"
_13
}
_13
},
_13
[...]
_13
}
_13
]

deleteImage

Use the following mutation to delete an image on File Manager using GraphQL:

Mutation:


_10
deleteImage(filename: String!){
_10
statusCode
_10
}

Response body example (200 OK):


_10
{
_10
"statusCode": "Ok"
_10
}

If the image does not exist, the statusCode value in the response will be NotFound.

See also
VTEX App Store
VTEX IO Apps