VTEX IO is a cloud-native platform that allows VTEX’s clients and partners to develop apps that integrate seamlessly with our ecosystem. This means that once a carrier creates an app on VTEX IO, the app can be made available to any given VTEX store. The store then can install it in order to integrate with that carrier’s service.

VTEX has its own CLI (command line interface), which enables you to perform different tasks required throughout the development process on VTEX IO. For example, it allows you to log in to your VTEX account, link your local files to the platform, or even publish and deprecate apps.

To install VTEX's CLI, you must first have Node.js and Yarn installed. See the VTEX IO CLI documentation to learn more about how to install it.

When developing carrier apps in VTEX IO, you can start by cloning one of the boilerplate repositories provided below (notification or tracking) to your machine.

To develop on VTEX IO, a user must have Admin or VTEX IO Developer permission. See this article for more information on accounts and permissions.

We recommend that you create a new workspace for development. Each workspace works as a separate version of the account in which you can develop your app and test it. To learn more, access our workspace documentation.

The manifest.json file contained in the boilerplate repository holds important app metadata, such as its name, version, and dependencies, among other things. It is the app’s first point of communication with VTEX IO.

After you clone the repository, you should update your app’s manifest.json file with its basic information.

You should be mindful of the billingOptions field. This field is used to define an app’s distribution on the platform and structure its pricing data, allowing the application usage to be public and, in some scenarios, even monetized. To know more about this field’s structure and how to fill it, see the Billing Options documentation.

To learn more about what information other fields must contain, see the Manifest documentation.

Below is an example of how some important fields could be filled in the manifest.json of a tracking app for an account named Example Carrier:

You should also install the VTEX integration hub apps on your account. There are two hubs, and you can install them by running:

• vtex install vtex.carrier-notifier
• vtex install vtex.carrier-tracking

Now you can run the command vtex link. With this, your local files will be linked to the platform, and you will be able to see the changes you make in the app working in real time.

Carrier integration apps should be developed in Node.js.

After you have released your app, stores will be able to install it to integrate with the carrier. Therefore, it is important to establish an authentication setting to ensure that only the carrier’s clients can use the app.

We recommend providing different credentials to each store that uses your app.

You can implement the authentication process by configuring app settings to ask the user to input login information. To do this, create a settingsSchema field in your manifest.json file, like the example below.

With these settings, whenever a store installs the app, they will be redirected to the Admin and required to provide a user and token. This does not authenticate the user but asks for the necessary information. It is up to the carrier to implement the internal authentication logic.

Below is an example of how to access these settings in your app.

If you want to test your authentication setting before publishing the app, you can do so whenever it is linked. In this case, go to the Admin page of your VTEX account, then go to Apps, My Apps, and open the settings of the linked app.

An error occurred while trying to load the image. https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/vtex-shipping-network/7440dcd-image1_128.png

An error occurred while trying to load the image. https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/vtex-shipping-network/9dbeb65-image2_130.png

Remember to access the admin in the same workspace the app has been linked to. The URL should be similar to this: https://{workspace}--{account}.{environment}.com/admin.

Carrier notification and tracking apps are meant to receive data from VTEX’s integration hubs. That is done through API calls made to your apps’ endpoints. These endpoints are described in the node/service.json file of the boilerplate repositories.

Note that the service.json file specifies the external behavior of your app's endpoints, not the internal logic applied to the received data. That logic must be implemented by the developer.

During development, you may need to test these endpoints but keep in mind that they are private, meaning that only users with permission can send requests to them. Calls to these endpoints must include an authorization header with an access token. You can run the command vtex local token command to get your token. Since this token contains the email registered to your VTEX account, you will need to set permission to that email in the service.json file, by changing @vtex.com.br to your own domain.

When you are done developing your app and have promoted it to the master workspace, it is ready to be published.

To do so, you may follow the steps described in this tutorial on how to make your new app version publicly available.

You may note that steps 3, 4, and 5 of the tutorial mentioned above are meant for stores creating apps for their own use. So, when creating carrier apps, they are not strictly necessary for the app to be made public since carrier apps are meant to be used by other accounts. In that case, steps 1, 2, and 6 should be sufficient, but we do recommend that you follow all steps in order to validate it thoroughly.

See the integration flow for carriers and learn more about notification and tracking.