VTEX IO apps are designed designed to seamlessly interface with VTEX Core Commerce APIs. These APIs provide a set of functionalities and data access points for managing and interacting with the VTEX e-commerce platform, enabling developers to perform various operations, such as managing orders, products, and customer data.

In this guide, you will learn how to create a custom client that can handle HTTP requests to these VTEX Core Commerce APIs, allowing your application to retrieve and manipulate data within the VTEX ecosystem.

Ensure a smooth development process by having the following prerequisites in place:

• VTEX IO Development Workspace: Set up your VTEX IO environment by following the steps outlined in Creating a Development Workspace.
• TypeScript Familiarity: Acquire a basic understanding of TypeScript, as we'll be using the node Builder for TypeScript development. For details, refer to Typescript's Official Documentation.
• Understanding of Clients: Clients play a crucial role in facilitating interactions between your application and both external and internal services. Learn more about Clients.

1. Start a new VTEX IO app using the node builder and open the project using your preferred code editor.

2. Install the @vtex/api package by running the following command:

   
   

   _10

   yarn add @vtex/api

   
   

3. Update the app's manifest.json to include the appropriate outbound-access policy for the requested URL. Here's a hypothetical example:

   manifest.json

   
   

   _22

   {

   _22

   "name": "your-app",

   _22

   "version": "1.0.0",

   _22

   "scripts": {

   _22

   // ...

   _22

   },

   _22

   "dependencies": {

   _22

   // ...

   _22

   },

   _22

   "builders": {

   _22

   // ...

   _22

   },

   _22

   "policies": [

   _22

   {

   _22

   "name": "outbound-access",

   _22

   "attrs": {

   _22

   "host": "{{account}}.vtexcommercestable.com.br",

   _22

   "path": "/api/checkout/pub/orderForm/*"

   _22

   }

   _22

   }

   _22

   ]

   _22

   }

   
   

1. Create a TypeScript file for your Client in the node/clients directory. Choose a name that easily identifies your Client (e.g., myClient.ts).

2. Create a client that represents the module you want to access. It will be a class that extends JanusClient.

   ./node/clients/myClient.ts

   
   

   _10

   import type { InstanceOptions, IOContext } from ‘@’vtex/api’

   _10

   import { JanusClient } from ‘@vtex/api’

   _10

   _10

   export default class MyClient extends JanusClient {

   _10

   constructor(context: IOContext, options?: InstanceOptions) {

   _10

   super(context, { …options })

   _10

   }

   _10

   }

   
   

3. In the constructor, set the VtexIdclientAutCookie header with the required token for authorization. Use ctx.authToken for the app's token, or ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken for requests from VTEX Admin or VTEX Storefront, respectively. Refer to App authentication using auth tokens for more information.

   ./node/clients/myClient.ts

   
   

   _16

   import type { InstanceOptions, IOContext } from ‘@’vtex/api’

   _16

   import { JanusClient } from ‘@vtex/api’

   _16

   _16

   export default class MyClient extends JanusClient {

   _16

   constructor(context: IOContext, options?: InstanceOptions) {

   _16

   super(ctx, {

   _16

   ...options,

   _16

   headers: {

   _16

   Accept: 'application/json',

   _16

   VtexIdclientAutCookie: ctx.storeUserAuthToken,

   _16

   'x-vtex-user-agent': ctx.userAgent,

   _16

   ...options?.headers,

   _16

   },

   _16

   })

   _16

   }

   _16

   }

   
   

   Ensure to export the Client from its module using either default or named export.

In your Client TypeScript file, implement the desired methods using the HttpClient for targeted HTTP calls.

In the provided example, the newOrderForm method is implemented to make HTTP requests using this.http. It facilitates the creation of a new order form by sending a POST request (postRaw) to the specified endpoint. The method includes additional configurations such as defining the metric for tracking and handling potential errors in the response.

Now that you've created your custom Client, organize and export it for use in your VTEX IO service. Follow these steps:

1. Create an index.ts file in the node/clients folder.

2. Inside the index.ts file, import the custom client you created in the previous step. For example:

   
   

   _10

   import MyClient from "./myClient.ts";

   
   

3. Define a class called Clients that extends IOClients. This class is used to organize and configure your custom Clients. Within the Clients class, declare a get property for each of your custom Clients. This property allows you to access a specific Client by name. In our example, we've created a client named myClient that uses the MyClient class.

   
   

   _10

   import { IOClients } from "@vtex/api";

   _10

   import MyClient from "./myClient.ts";

   _10

   _10

   export class Clients extends IOClients {

   _10

   public get status() {

   _10

   return this.getOrSet("myClient", MyClient);

   _10

   }

   _10

   }

   
   

Now that you have developed and exported your custom Client to communicate with the desired service, your Clients can be accessed and used within your VTEX IO service to perform various tasks. Learn how to use clients effectively in the Using Node Clients guide.

• GraphQL apps: Some Core Commerce modules already feature a GraphQL app that abstracts their endpoints. Check if the desired data is available via one of our GraphQL apps. Utilize the GraphQL IDE app on the Admin for exploration.
• Authentication: IO apps do not require an appKey/appToken pair to make requests to VTEX Core Commerce APIs. Every app has its own rotating token that can be used on the app's code. In scenarios where using the app's token is not ideal (e.g., authorization depends on the calling user), opt to use the user's token instead, using ctx.vtex.storeUserAuthToken or ctx.vtex.adminUserAuthToken. Refer to Authentication for more information.

• CheckoutClient