About the VTEX category

Alumio_Bot · September 21, 2022, 10:00am

Add topics about this connector package here.
Always check the ‘How to use the Alumio connector packages’ topic.

Extra information

System documentation: VTEX API Reference

Connector package documentation

1. Setting up HTTP Client VTEX

1.1 Steps

In the Alumio Dashboard, go to Clients → HTTP Clients. Create a new HTTP Client and select the VTEX Client as the HTTP Client.
Fill in the Base URI, Application Key, and Application Token according to your VTEX account and the application keys created on VTEX.
(For more information, see VTEX Application Keys
You can optionally enable the logging of request to get the log of the authentication.
Save the HTTP Client for use.

2. Subscribing to Entities from VTEX

2.1 Steps

Go to Connections → Incoming and create a new incoming configuration and select the VTEX Subscriber as the subscriber.
Select the entity you want to subscribe to from VTEX.
Add any request parameters needed to subscribe to the entity. Please refer to an example in the General Concept section.
You can optionally add a transformer to transform the request parameters into something you will request from VTEX.
Select the VTEX HTTP Client to use.
You can also optionally enable pagination to allow Alumio to fetch paginated entities. For VTEX case, you should use Increase query parameter as pagination type (only available for some entities).

“Path” is the path parameter of the URL. For example the {id}.
“Query” is a defined set of parameters attached to the end of a URL.
Example: www.url.com?type=true&start=0

2.2 General Concept

We follow VTEX documentation on building this connector so you can easily use the connector based on the VTEX API Reference.

Entity

The entity you want to subscribe to VTEX. Please refer to the entities in Management APIs from VTEX API Reference page.

Request Parameters

These are the parameters you can provide to get the needed entity based on the VTEX API Reference.

Please look at the example below on how to fill the “Request Parameters” field when subscribing to the “Retrieve user order details” entity. We can see in the documentation that the “Retrieve user order details” entity requires orderId as a path parameter to define which order we want to fetch the details from.

To fill the “orderId” with the actual order ID you want to get the details from, we need to define the “orderId” key inside path key in the Request Parameters field. Besides orderId in path parameters, the documentation also describes that the clientEmail is also a required parameter, but it should be defined in the query parameters. So, we need to define it inside the query key in the Request Parameters field. The keys inside query parameters (in this example would be “clientEmail”) will be parsed as query parameters. Here is how we should fill the Request Parameters field:

Alumio will then send this to the VTEX as
/api/oms/user/orders/12345?clientemail=john@example.com

Input Transformer

Any transformers set here will be executed after the Request Parameters are loaded. So, you can add any transformer to provide and manipulate the request parameters into anything you need, either as path parameters and/or as query parameters of an entity.

HTTP Client

The HTTP Client configuration you will use to access VTEX.

Follow Pagination

If we want to fetch a list of entities, some systems have pagination to limit the entities returned in one call. VTEX is one of the systems, but not all VTEX entities support pagination. Some entities that support pagination are Catalog - Get Brand List Per Page, Orders - List Orders, etc. By selecting any pagination type in VTEX subscriber, Alumio will fetch a number of pages according to the number entered in the “Maximum number of pages to fetch” field, instead of fetching only one page. Of course, such behavior happens if the response matches the criteria configured in the subscriber.

For example, we want to fetch a paginated list of orders. Please select “Orders – List orders” entity and fill the form such as below.

By defining “per_page” property under query parameter, it means we want to fetch 5 orders per page. By referring to the documentation, the parameter to define which page we want to fetch is named “page”. We need to define it in the “Query parameter to set for paging” field. We also need to specify the value of “per_page” into the “Expected number of items” field. Fill in the “Maximum number of pages to fetch” with the number of how many pages you want to fetch. When Alumio fetched the number of pages, it will stop fetching pages. One more step to enable the pagination is by selecting the “Storage to track the process”. You can create a new storage and use it here in the incoming configuration.

3. Publishing Entity to VTEX

3.1 Steps

Go to Connections → Outgoing, create a new outgoing configuration and select VTEX Publisher as the publisher.
Select the Method that you want the publisher to perform with the data.
Select the VTEX entity you want the data to be published to.
You can optionally add any path data to the request on the key path.
You can optionally add any query data to the request on the key query.
You can optionally add any payload data to the request on the key payload.
Select the HTTP Client to use.

3.2 General Concept

Like the subscriber, the publisher has similar methods on how to use it. The difference is the payload that will be submitted by the publisher originating from the data (from routes, from transformers in outgoing configuration), though you can also add or modify the payload using the Request Transformer.

Method

Currently we support POST, PUT, PATCH and DELETE methods on submitting data to VTEX.

Entity

We support publishing to most VTEX endpoints.
Please refer to VTEX API Reference page.
Based on the documentation, some endpoints may need one or more path parameters.

For example, we want to update a brand. Please select “PUT” as the method and “Catalog – Update Brand” as the entity of the publisher.

The documentation says that we need “brandId” as path parameters. In that case, you need to provide the “brandId” key into the path key in the data, either as an output from Routes or output from Transformers in the Outgoing Configuration. And you can put the payload you want to send to VTEX into the payload key in the data. Here is an example of the required data:

Alumio will send an API request to VTEX with URL /api/catalog/pvt/brand/123 and the body will be like this:

“Path” is the path parameter of the URL. For example the {id}.
“Query” is a defined set of parameters attached to the end of a URL.
Example: www.url.com?type=true&start=0
“Payload” is the data contained within a request.